@twentyhq/people-data-labs 1.0.0

package/src/logic-functions/utils/extract-company-match-params.ts

@@ -0,0 +1,52 @@
+import { normalizeDomain } from 'src/logic-functions/utils/normalize-domain';
+import { normalizeLinkedinUrl } from 'src/logic-functions/utils/normalize-linkedin-url';
+import { resolveMinLikelihood } from 'src/logic-functions/utils/resolve-min-likelihood';
+import { toText } from 'src/logic-functions/utils/to-text';
+import { type BulkEnrichInput } from 'src/types/bulk-enrich-input';
+import { type CompanyNode } from 'src/types/company-node';
+import { type PdlCompanyEnrichParams } from 'src/types/pdl-company-enrich-params';
+import { isDefined } from 'src/utils/is-defined';
+import { pruneUndefined } from 'src/utils/prune-undefined';
+
+export const extractCompanyMatchParams = ({
+  node,
+  input,
+}: {
+  node: CompanyNode;
+  input: BulkEnrichInput;
+}): PdlCompanyEnrichParams | undefined => {
+  const existingPdlId = toText(node.pdlId);
+  if (isDefined(existingPdlId)) {
+    return {
+      pdlId: existingPdlId,
+      minLikelihood: resolveMinLikelihood({
+        inputMinLikelihood: input.minLikelihood,
+        hasStrongIdentifier: true,
+      }),
+    };
+  }
+
+  const websiteDomain = normalizeDomain(node.domainName?.primaryLinkUrl);
+  const linkedinProfileUrl = normalizeLinkedinUrl(node.linkedinLink?.primaryLinkUrl);
+  const companyName = toText(node.name);
+  const hasStrongIdentifier =
+    isDefined(websiteDomain) || isDefined(linkedinProfileUrl);
+
+  const companyMatchParams = pruneUndefined({
+    website: websiteDomain,
+    profile: linkedinProfileUrl,
+    name: companyName,
+  });
+
+  if (Object.keys(companyMatchParams).length === 0) {
+    return undefined;
+  }
+
+  return {
+    ...companyMatchParams,
+    minLikelihood: resolveMinLikelihood({
+      inputMinLikelihood: input.minLikelihood,
+      hasStrongIdentifier,
+    }),
+  };
+};

package/src/logic-functions/utils/extract-pdl-error-message.ts

@@ -0,0 +1,47 @@
+import { isNonEmptyString, isObject, isString } from '@sniptt/guards';
+
+import { isDefined } from 'src/utils/is-defined';
+
+const extractMessageFromValue = (
+  messageValue: unknown,
+): string | undefined => {
+  if (isNonEmptyString(messageValue)) {
+    return messageValue;
+  }
+
+  if (Array.isArray(messageValue)) {
+    const joinedMessages = messageValue.filter(isString).join('; ');
+
+    return isNonEmptyString(joinedMessages) ? joinedMessages : undefined;
+  }
+
+  return undefined;
+};
+
+export const extractPdlErrorMessage = ({
+  json,
+  httpStatus,
+}: {
+  json: Record<string, unknown>;
+  httpStatus: number;
+}): string => {
+  const errorField = json.error;
+
+  if (isObject(errorField)) {
+    const messageFromErrorObject = extractMessageFromValue(
+      (errorField as Record<string, unknown>).message,
+    );
+    if (isDefined(messageFromErrorObject)) {
+      return messageFromErrorObject;
+    }
+  }
+
+  const messageFromTopLevelField =
+    extractMessageFromValue(errorField) ??
+    extractMessageFromValue(json.message);
+  if (isDefined(messageFromTopLevelField)) {
+    return messageFromTopLevelField;
+  }
+
+  return `PDL request failed (HTTP ${httpStatus}).`;
+};

package/src/logic-functions/utils/extract-person-match-params.ts

@@ -0,0 +1,59 @@
+import { buildPersonNameParam } from 'src/logic-functions/utils/build-person-name-param';
+import { resolveMinLikelihood } from 'src/logic-functions/utils/resolve-min-likelihood';
+import { toText } from 'src/logic-functions/utils/to-text';
+import { type BulkEnrichInput } from 'src/types/bulk-enrich-input';
+import { type PdlPersonEnrichParams } from 'src/types/pdl-person-enrich-params';
+import { type PersonNode } from 'src/types/person-node';
+import { isDefined } from 'src/utils/is-defined';
+import { pruneUndefined } from 'src/utils/prune-undefined';
+
+export const extractPersonMatchParams = ({
+  node,
+  input,
+}: {
+  node: PersonNode;
+  input: BulkEnrichInput;
+}): PdlPersonEnrichParams | undefined => {
+  const existingPdlId = toText(node.pdlId);
+  if (isDefined(existingPdlId)) {
+    return {
+      pdlId: existingPdlId,
+      minLikelihood: resolveMinLikelihood({
+        inputMinLikelihood: input.minLikelihood,
+        hasStrongIdentifier: true,
+      }),
+    };
+  }
+
+  const linkedinProfileUrl = toText(node.linkedinLink?.primaryLinkUrl);
+  const primaryEmail = toText(node.emails?.primaryEmail);
+  const fullName = buildPersonNameParam({
+    firstName: node.name?.firstName,
+    lastName: node.name?.lastName,
+  });
+  const companyName = toText(node.company?.name);
+  const hasStrongIdentifier =
+    isDefined(linkedinProfileUrl) || isDefined(primaryEmail);
+
+  const nameIsUsableAsMatchSignal =
+    isDefined(fullName) && (hasStrongIdentifier || isDefined(companyName));
+
+  const personMatchParams = pruneUndefined({
+    profile: linkedinProfileUrl,
+    email: primaryEmail,
+    name: nameIsUsableAsMatchSignal ? fullName : undefined,
+    company: nameIsUsableAsMatchSignal ? companyName : undefined,
+  });
+
+  if (Object.keys(personMatchParams).length === 0) {
+    return undefined;
+  }
+
+  return {
+    ...personMatchParams,
+    minLikelihood: resolveMinLikelihood({
+      inputMinLikelihood: input.minLikelihood,
+      hasStrongIdentifier,
+    }),
+  };
+};

package/src/logic-functions/utils/extract-record-ids.ts

@@ -0,0 +1,18 @@
+import { isNonEmptyString } from '@sniptt/guards';
+
+import { type RecordInput } from 'src/types/bulk-enrich-input';
+
+export const extractRecordIds = (
+  records: RecordInput | RecordInput[],
+): string[] => {
+  const recordsAsArray =
+    records === null || records === undefined
+      ? []
+      : Array.isArray(records)
+        ? records
+        : [records];
+
+  return recordsAsArray
+    .map((record) => (typeof record === 'string' ? record : record?.id))
+    .filter((id): id is string => isNonEmptyString(id));
+};

package/src/logic-functions/utils/find-company-id-by-filter.ts

@@ -0,0 +1,28 @@
+import { type CoreApiClient } from 'twenty-client-sdk/core';
+
+type CompaniesConnection = { edges?: { node: { id: string } }[] };
+
+export const findCompanyIdByFilter = async ({
+  client,
+  filter,
+  requireUnique = false,
+}: {
+  client: CoreApiClient;
+  filter: Record<string, unknown>;
+  requireUnique?: boolean;
+}): Promise<string | undefined> => {
+  const result = (await client.query({
+    companies: {
+      __args: { filter, first: requireUnique ? 2 : 1 },
+      edges: { node: { id: true } },
+    },
+  })) as { companies?: CompaniesConnection };
+
+  const edges = result.companies?.edges ?? [];
+
+  if (requireUnique && edges.length !== 1) {
+    return undefined;
+  }
+
+  return edges[0]?.node?.id;
+};

package/src/logic-functions/utils/find-company-id.ts

@@ -0,0 +1,59 @@
+import { isNonEmptyString } from '@sniptt/guards';
+import { type CoreApiClient } from 'twenty-client-sdk/core';
+
+import { findCompanyIdByFilter } from 'src/logic-functions/utils/find-company-id-by-filter';
+import { type CompanyMatchKeys } from 'src/types/company-match-keys';
+import { isDefined } from 'src/utils/is-defined';
+
+export const findCompanyId = async ({
+  client,
+  matchKeys,
+}: {
+  client: CoreApiClient;
+  matchKeys: CompanyMatchKeys;
+}): Promise<string | undefined> => {
+  const { pdlId, website, linkedinUrl, name } = matchKeys;
+
+  if (isNonEmptyString(pdlId)) {
+    const matchById = await findCompanyIdByFilter({
+      client,
+      filter: { pdlId: { eq: pdlId } },
+    });
+    if (isDefined(matchById)) {
+      return matchById;
+    }
+  }
+
+  if (isNonEmptyString(website)) {
+    const matchByDomain = await findCompanyIdByFilter({
+      client,
+      filter: { domainName: { primaryLinkUrl: { eq: website } } },
+    });
+    if (isDefined(matchByDomain)) {
+      return matchByDomain;
+    }
+  }
+
+  if (isNonEmptyString(linkedinUrl)) {
+    const matchByLinkedin = await findCompanyIdByFilter({
+      client,
+      filter: { linkedinLink: { primaryLinkUrl: { eq: linkedinUrl } } },
+    });
+    if (isDefined(matchByLinkedin)) {
+      return matchByLinkedin;
+    }
+  }
+
+  if (isNonEmptyString(name)) {
+    const matchByName = await findCompanyIdByFilter({
+      client,
+      filter: { name: { eq: name } },
+      requireUnique: true,
+    });
+    if (isDefined(matchByName)) {
+      return matchByName;
+    }
+  }
+
+  return undefined;
+};

package/src/logic-functions/utils/find-existing-workflow-id.ts

@@ -0,0 +1,18 @@
+import { type CoreApiClient } from 'twenty-client-sdk/core';
+
+export const findExistingWorkflowId = async ({
+  client,
+  name,
+}: {
+  client: CoreApiClient;
+  name: string;
+}): Promise<string | undefined> => {
+  const result = (await client.query({
+    workflows: {
+      __args: { filter: { name: { eq: name } } },
+      edges: { node: { id: true } },
+    },
+  })) as { workflows?: { edges?: { node?: { id?: string } }[] } };
+
+  return result.workflows?.edges?.[0]?.node?.id;
+};

package/src/logic-functions/utils/find-or-create-current-company.ts

@@ -0,0 +1,108 @@
+import { isNonEmptyString } from '@sniptt/guards';
+import { type CoreApiClient } from 'twenty-client-sdk/core';
+
+import { PdlOperationError } from 'src/logic-functions/errors/pdl-operation-error';
+import { buildCompanyCreateData } from 'src/logic-functions/utils/build-company-create-data';
+import { buildCompanyMatchKeys } from 'src/logic-functions/utils/build-company-match-keys';
+import { findCompanyId } from 'src/logic-functions/utils/find-company-id';
+import { type CompanyIdByMatchKeyCache } from 'src/types/company-id-by-match-key-cache';
+import { type CompanyMatchKeys } from 'src/types/company-match-keys';
+import { type PdlPersonData } from 'src/types/pdl-person-data';
+import { isDefined } from 'src/utils/is-defined';
+import { isUniqueViolationError } from 'src/utils/is-unique-violation-error';
+
+type CreateCompanyResult = { createCompany?: { id?: string } };
+
+const findOrCreateUncachedCompany = async ({
+  client,
+  personData,
+  companyMatchKeys,
+}: {
+  client: CoreApiClient;
+  personData: PdlPersonData;
+  companyMatchKeys: CompanyMatchKeys;
+}): Promise<string | undefined> => {
+  const existingCompanyId = await findCompanyId({
+    client,
+    matchKeys: companyMatchKeys,
+  });
+  if (isDefined(existingCompanyId)) {
+    return existingCompanyId;
+  }
+
+  const canCreateNewCompany =
+    isNonEmptyString(companyMatchKeys.name) ||
+    isNonEmptyString(companyMatchKeys.website);
+
+  if (!canCreateNewCompany) {
+    return undefined;
+  }
+
+  try {
+    const createCompanyResult = (await client.mutation({
+      createCompany: {
+        __args: { data: buildCompanyCreateData(personData) },
+        id: true,
+      },
+    })) as CreateCompanyResult;
+
+    const createdCompanyId = createCompanyResult.createCompany?.id;
+
+    if (!isDefined(createdCompanyId)) {
+      throw new PdlOperationError('Failed to create company: no id returned.');
+    }
+
+    return createdCompanyId;
+  } catch (createCompanyError) {
+    if (!isUniqueViolationError(createCompanyError)) {
+      throw createCompanyError;
+    }
+
+    const raceWinnerCompanyId = await findCompanyId({
+      client,
+      matchKeys: companyMatchKeys,
+    });
+    if (isDefined(raceWinnerCompanyId)) {
+      return raceWinnerCompanyId;
+    }
+
+    throw createCompanyError;
+  }
+};
+
+export const findOrCreateCurrentCompany = async ({
+  client,
+  personData,
+  companyIdByMatchKeyCache,
+}: {
+  client: CoreApiClient;
+  personData: PdlPersonData;
+  companyIdByMatchKeyCache: CompanyIdByMatchKeyCache;
+}): Promise<string | undefined> => {
+  const companyMatchKeys = buildCompanyMatchKeys(personData);
+
+  const hasAnyCompanyMatchKey =
+    isNonEmptyString(companyMatchKeys.pdlId) ||
+    isNonEmptyString(companyMatchKeys.website) ||
+    isNonEmptyString(companyMatchKeys.linkedinUrl) ||
+    isNonEmptyString(companyMatchKeys.name);
+
+  if (!hasAnyCompanyMatchKey) {
+    return undefined;
+  }
+
+  const companyMatchKeyCacheKey = JSON.stringify(companyMatchKeys);
+  if (companyIdByMatchKeyCache.has(companyMatchKeyCacheKey)) {
+    return companyIdByMatchKeyCache.get(companyMatchKeyCacheKey);
+  }
+
+  const resolvedCompanyId = await findOrCreateUncachedCompany({
+    client,
+    personData,
+    companyMatchKeys,
+  });
+
+  companyIdByMatchKeyCache.set(companyMatchKeyCacheKey, resolvedCompanyId);
+
+  return resolvedCompanyId;
+};

package/src/logic-functions/utils/get-pdl-api-key.ts

@@ -0,0 +1,15 @@
+import { isNonEmptyString } from '@sniptt/guards';
+
+import { PdlConfigError } from 'src/logic-functions/errors/pdl-config-error';
+
+export const getPdlApiKey = (): string => {
+  const apiKey = process.env.PDL_API_KEY?.trim();
+
+  if (!isNonEmptyString(apiKey)) {
+    throw new PdlConfigError(
+      'PDL_API_KEY is not set. The workspace admin must configure the People Data Labs API key in Settings -> Apps.',
+    );
+  }
+
+  return apiKey;
+};

package/src/logic-functions/utils/internal-field-names.ts

@@ -0,0 +1,6 @@
+export const INTERNAL_BOOKKEEPING_FIELDS: ReadonlySet<string> = new Set([
+  'pdlRawPayload',
+  'pdlLastEnrichedAt',
+  'pdlEnrichmentStatus',
+  'pdlLikelihood',
+]);

package/src/logic-functions/utils/is-empty-address.ts

@@ -0,0 +1,20 @@
+import { isObject } from '@sniptt/guards';
+
+import { isEmptyText } from 'src/logic-functions/utils/is-empty-text';
+
+export const isEmptyAddress = (value: unknown): boolean => {
+  if (!isObject(value)) {
+    return true;
+  }
+
+  const record = value as Record<string, unknown>;
+
+  return (
+    isEmptyText(record.addressStreet1) &&
+    isEmptyText(record.addressStreet2) &&
+    isEmptyText(record.addressCity) &&
+    isEmptyText(record.addressPostcode) &&
+    isEmptyText(record.addressState) &&
+    isEmptyText(record.addressCountry)
+  );
+};

package/src/logic-functions/utils/is-empty-emails.ts

@@ -0,0 +1,13 @@
+import { isObject } from '@sniptt/guards';
+
+import { isEmptyText } from 'src/logic-functions/utils/is-empty-text';
+
+export const isEmptyEmails = (value: unknown): boolean => {
+  if (!isObject(value)) {
+    return true;
+  }
+
+  const record = value as Record<string, unknown>;
+
+  return isEmptyText(record.primaryEmail);
+};

package/src/logic-functions/utils/is-empty-full-name.ts

@@ -0,0 +1,13 @@
+import { isObject } from '@sniptt/guards';
+
+import { isEmptyText } from 'src/logic-functions/utils/is-empty-text';
+
+export const isEmptyFullName = (value: unknown): boolean => {
+  if (!isObject(value)) {
+    return true;
+  }
+
+  const record = value as Record<string, unknown>;
+
+  return isEmptyText(record.firstName) && isEmptyText(record.lastName);
+};

package/src/logic-functions/utils/is-empty-links.ts

@@ -0,0 +1,13 @@
+import { isObject } from '@sniptt/guards';
+
+import { isEmptyText } from 'src/logic-functions/utils/is-empty-text';
+
+export const isEmptyLinks = (value: unknown): boolean => {
+  if (!isObject(value)) {
+    return true;
+  }
+
+  const record = value as Record<string, unknown>;
+
+  return isEmptyText(record.primaryLinkUrl);
+};

package/src/logic-functions/utils/is-empty-phones.ts

@@ -0,0 +1,13 @@
+import { isObject } from '@sniptt/guards';
+
+import { isEmptyText } from 'src/logic-functions/utils/is-empty-text';
+
+export const isEmptyPhones = (value: unknown): boolean => {
+  if (!isObject(value)) {
+    return true;
+  }
+
+  const record = value as Record<string, unknown>;
+
+  return isEmptyText(record.primaryPhoneNumber);
+};

package/src/logic-functions/utils/is-empty-text.ts

@@ -0,0 +1,4 @@
+import { toText } from 'src/logic-functions/utils/to-text';
+import { isDefined } from 'src/utils/is-defined';
+
+export const isEmptyText = (value: unknown): boolean => !isDefined(toText(value));

package/src/logic-functions/utils/map-company.ts

@@ -0,0 +1,115 @@
+import { COMPANY_TYPE_OPTIONS } from 'src/constants/company-type-options';
+import { FUNDING_STAGE_OPTIONS } from 'src/constants/funding-stage-options';
+import { INDUSTRY_OPTIONS } from 'src/constants/industry-options';
+import { LOCATION_CONTINENT_OPTIONS } from 'src/constants/location-continent-options';
+import { METRO_OPTIONS } from 'src/constants/metro-options';
+import { MIC_EXCHANGE_OPTIONS } from 'src/constants/mic-exchange-options';
+import { SIZE_OPTIONS } from 'src/constants/size-options';
+import { toJsonArray } from 'src/logic-functions/utils/to-json-array';
+import { toJsonObject } from 'src/logic-functions/utils/to-json-object';
+import { toNumber } from 'src/logic-functions/utils/to-number';
+import { toStringArray } from 'src/logic-functions/utils/to-string-array';
+import { toText } from 'src/logic-functions/utils/to-text';
+import { buildAddress } from 'src/logic-functions/utils/build-address';
+import { buildCurrencyFromUsd } from 'src/logic-functions/utils/build-currency-from-usd';
+import { buildLinks } from 'src/logic-functions/utils/build-links';
+import { normalizeDomain } from 'src/logic-functions/utils/normalize-domain';
+import { normalizeLinkedinUrl } from 'src/logic-functions/utils/normalize-linkedin-url';
+import { parsePartialDate } from 'src/logic-functions/utils/parse-partial-date';
+import { buildAllowedValues } from 'src/logic-functions/utils/build-allowed-values';
+import { pickMultiSelect } from 'src/logic-functions/utils/pick-multi-select';
+import { pickSelect } from 'src/logic-functions/utils/pick-select';
+import { sizeTransform } from 'src/logic-functions/utils/size-transform';
+import { type MappedRecord } from 'src/types/mapped-record';
+import { type PdlCompanyData } from 'src/types/pdl-company-data';
+import { pruneUndefined } from 'src/utils/prune-undefined';
+
+const INDUSTRY_VALUES = buildAllowedValues(INDUSTRY_OPTIONS);
+const COMPANY_TYPE_VALUES = buildAllowedValues(COMPANY_TYPE_OPTIONS);
+const SIZE_VALUES = buildAllowedValues(SIZE_OPTIONS);
+const METRO_VALUES = buildAllowedValues(METRO_OPTIONS);
+const LOCATION_CONTINENT_VALUES = buildAllowedValues(LOCATION_CONTINENT_OPTIONS);
+const MIC_EXCHANGE_VALUES = buildAllowedValues(MIC_EXCHANGE_OPTIONS);
+const FUNDING_STAGE_VALUES = buildAllowedValues(FUNDING_STAGE_OPTIONS);
+
+export const mapCompany = (companyData: PdlCompanyData): MappedRecord => {
+  const location = companyData.location ?? {};
+
+  const standard = pruneUndefined({
+    name: toText(companyData.display_name) ?? toText(companyData.name),
+    domainName: buildLinks({ url: normalizeDomain(companyData.website) }),
+    linkedinLink: buildLinks({ url: normalizeLinkedinUrl(companyData.linkedin_url) }),
+    address: buildAddress({
+      street1: location.street_address,
+      street2: location.address_line_2,
+      city: location.locality,
+      postcode: location.postal_code,
+      state: location.region,
+      country: location.country,
+      geo: location.geo,
+    }),
+  });
+
+  const pdl = pruneUndefined({
+    pdlId: toText(companyData.id),
+
+    pdlIndustry: pickSelect({ raw: companyData.industry, allowedValues: INDUSTRY_VALUES }),
+    pdlIndustryDetail: toText(companyData.industry_v2),
+    pdlCompanyType: pickSelect({
+      raw: companyData.type,
+      allowedValues: COMPANY_TYPE_VALUES,
+    }),
+    pdlSizeRange: pickSelect({
+      raw: companyData.size,
+      allowedValues: SIZE_VALUES,
+      transform: sizeTransform,
+    }),
+    pdlLocationMetro: pickSelect({
+      raw: location.metro,
+      allowedValues: METRO_VALUES,
+    }),
+    pdlLocationContinent: pickSelect({
+      raw: location.continent,
+      allowedValues: LOCATION_CONTINENT_VALUES,
+    }),
+    pdlMicExchange: pickSelect({
+      raw: companyData.mic_exchange,
+      allowedValues: MIC_EXCHANGE_VALUES,
+    }),
+
+    pdlLegalName: toText(companyData.legal_name),
+    pdlHeadline: toText(companyData.headline),
+    pdlSummary: toText(companyData.summary),
+    pdlTicker: toText(companyData.ticker),
+    pdlLinkedinId: toText(companyData.linkedin_id),
+
+    pdlEmployeeCount: toNumber(companyData.employee_count),
+    pdlFoundedYear: toNumber(companyData.founded),
+    pdlNumberFundingRounds: toNumber(companyData.number_funding_rounds),
+
+    pdlTotalFunding: buildCurrencyFromUsd(companyData.total_funding_raised),
+    pdlLatestFundingStage: pickSelect({
+      raw: companyData.latest_funding_stage,
+      allowedValues: FUNDING_STAGE_VALUES,
+    }),
+    pdlFundingStages: pickMultiSelect({
+      rawValues: companyData.funding_stages,
+      allowedValues: FUNDING_STAGE_VALUES,
+    }),
+    pdlLastFundingDate: parsePartialDate(companyData.last_funding_date),
+
+    pdlTwitterUrl: buildLinks({ url: companyData.twitter_url }),
+    pdlFacebookUrl: buildLinks({ url: companyData.facebook_url }),
+
+    pdlTags: toStringArray(companyData.tags),
+    pdlAlternativeNames: toStringArray(companyData.alternative_names),
+    pdlAlternativeDomains: toStringArray(companyData.alternative_domains),
+    pdlAffiliatedProfiles: toStringArray(companyData.profiles),
+
+    pdlNaics: toJsonArray(companyData.naics),
+    pdlSic: toJsonArray(companyData.sic),
+    pdlEmployeeCountByCountry: toJsonObject(companyData.employee_count_by_country),
+  });
+
+  return { standard, pdl };
+};