@twentyhq/people-data-labs 1.0.0

package/src/logic-functions/utils/__tests__/to-json-array.spec.ts

@@ -0,0 +1,16 @@
+import { describe, expect, it } from 'vitest';
+
+import { toJsonArray } from 'src/logic-functions/utils/to-json-array';
+
+describe('toJsonArray', () => {
+  it('returns a non-empty array unchanged', () => {
+    const value = [{ a: 1 }];
+
+    expect(toJsonArray(value)).toBe(value);
+  });
+
+  it('returns undefined for empty arrays and non-arrays', () => {
+    expect(toJsonArray([])).toBeUndefined();
+    expect(toJsonArray({ a: 1 })).toBeUndefined();
+  });
+});

package/src/logic-functions/utils/__tests__/to-json-object.spec.ts

@@ -0,0 +1,18 @@
+import { describe, expect, it } from 'vitest';
+
+import { toJsonObject } from 'src/logic-functions/utils/to-json-object';
+
+describe('toJsonObject', () => {
+  it('returns a non-empty plain object unchanged', () => {
+    const value = { country: { us: 10 } };
+
+    expect(toJsonObject(value)).toBe(value);
+  });
+
+  it('returns undefined for empty objects, arrays and non-objects', () => {
+    expect(toJsonObject({})).toBeUndefined();
+    expect(toJsonObject([1, 2])).toBeUndefined();
+    expect(toJsonObject('x')).toBeUndefined();
+    expect(toJsonObject(null)).toBeUndefined();
+  });
+});

package/src/logic-functions/utils/__tests__/to-number.spec.ts

@@ -0,0 +1,17 @@
+import { describe, expect, it } from 'vitest';
+
+import { toNumber } from 'src/logic-functions/utils/to-number';
+
+describe('toNumber', () => {
+  it('returns finite numbers including zero', () => {
+    expect(toNumber(0)).toBe(0);
+    expect(toNumber(120)).toBe(120);
+  });
+
+  it('returns undefined for non-finite numbers and non-numbers', () => {
+    expect(toNumber(Number.NaN)).toBeUndefined();
+    expect(toNumber(Number.POSITIVE_INFINITY)).toBeUndefined();
+    expect(toNumber('120')).toBeUndefined();
+    expect(toNumber(null)).toBeUndefined();
+  });
+});

package/src/logic-functions/utils/__tests__/to-string-array.spec.ts

@@ -0,0 +1,17 @@
+import { describe, expect, it } from 'vitest';
+
+import { toStringArray } from 'src/logic-functions/utils/to-string-array';
+
+describe('toStringArray', () => {
+  it('cleans, trims and dedupes string entries', () => {
+    expect(toStringArray([' a ', 'b', 'a', '', 3, null])).toEqual(['a', 'b']);
+  });
+
+  it('returns undefined for a non-array', () => {
+    expect(toStringArray('a')).toBeUndefined();
+  });
+
+  it('returns undefined when nothing usable remains', () => {
+    expect(toStringArray(['', '   ', null])).toBeUndefined();
+  });
+});

package/src/logic-functions/utils/__tests__/to-text.spec.ts

@@ -0,0 +1,20 @@
+import { describe, expect, it } from 'vitest';
+
+import { toText } from 'src/logic-functions/utils/to-text';
+
+describe('toText', () => {
+  it('trims and returns a non-empty string', () => {
+    expect(toText('  hello  ')).toBe('hello');
+  });
+
+  it('returns undefined for an empty or whitespace string', () => {
+    expect(toText('')).toBeUndefined();
+    expect(toText('   ')).toBeUndefined();
+  });
+
+  it('returns undefined for non-string values', () => {
+    expect(toText(42)).toBeUndefined();
+    expect(toText(null)).toBeUndefined();
+    expect(toText(undefined)).toBeUndefined();
+  });
+});

package/src/logic-functions/utils/__tests__/update-companies-status.spec.ts

@@ -0,0 +1,32 @@
+import { describe, expect, it } from 'vitest';
+
+import { createCoreApiClientMock } from 'src/logic-functions/__mocks__/create-core-api-client-mock';
+import { updateCompaniesStatus } from 'src/logic-functions/utils/update-companies-status';
+
+describe('updateCompaniesStatus', () => {
+  it('updates many companies via an id-in filter', async () => {
+    let request: Record<string, unknown> | undefined;
+    const client = createCoreApiClientMock({
+      onMutation: (received) => {
+        request = received as Record<string, unknown>;
+      },
+    });
+
+    await updateCompaniesStatus({
+      client,
+      recordIds: ['c1', 'c2'],
+      data: {
+        pdlEnrichmentStatus: 'ERROR',
+      },
+    });
+
+    expect(request).toMatchObject({
+      updateCompanies: {
+        __args: {
+          filter: { id: { in: ['c1', 'c2'] } },
+          data: { pdlEnrichmentStatus: 'ERROR' },
+        },
+      },
+    });
+  });
+});

package/src/logic-functions/utils/__tests__/update-company-record.spec.ts

@@ -0,0 +1,25 @@
+import { describe, expect, it } from 'vitest';
+
+import { createCoreApiClientMock } from 'src/logic-functions/__mocks__/create-core-api-client-mock';
+import { updateCompanyRecord } from 'src/logic-functions/utils/update-company-record';
+
+describe('updateCompanyRecord', () => {
+  it('updates a single company by id', async () => {
+    let request: Record<string, unknown> | undefined;
+    const client = createCoreApiClientMock({
+      onMutation: (received) => {
+        request = received as Record<string, unknown>;
+      },
+    });
+
+    await updateCompanyRecord({
+      client,
+      recordId: 'c1',
+      data: { name: 'Acme Corp' },
+    });
+
+    expect(request).toMatchObject({
+      updateCompany: { __args: { id: 'c1', data: { name: 'Acme Corp' } } },
+    });
+  });
+});

package/src/logic-functions/utils/__tests__/update-people-status.spec.ts

@@ -0,0 +1,32 @@
+import { describe, expect, it } from 'vitest';
+
+import { createCoreApiClientMock } from 'src/logic-functions/__mocks__/create-core-api-client-mock';
+import { updatePeopleStatus } from 'src/logic-functions/utils/update-people-status';
+
+describe('updatePeopleStatus', () => {
+  it('updates many people via an id-in filter', async () => {
+    let request: Record<string, unknown> | undefined;
+    const client = createCoreApiClientMock({
+      onMutation: (received) => {
+        request = received as Record<string, unknown>;
+      },
+    });
+
+    await updatePeopleStatus({
+      client,
+      recordIds: ['p1', 'p2'],
+      data: {
+        pdlEnrichmentStatus: 'NOT_FOUND',
+      },
+    });
+
+    expect(request).toMatchObject({
+      updatePeople: {
+        __args: {
+          filter: { id: { in: ['p1', 'p2'] } },
+          data: { pdlEnrichmentStatus: 'NOT_FOUND' },
+        },
+      },
+    });
+  });
+});

package/src/logic-functions/utils/__tests__/update-person-record.spec.ts

@@ -0,0 +1,25 @@
+import { describe, expect, it } from 'vitest';
+
+import { createCoreApiClientMock } from 'src/logic-functions/__mocks__/create-core-api-client-mock';
+import { updatePersonRecord } from 'src/logic-functions/utils/update-person-record';
+
+describe('updatePersonRecord', () => {
+  it('updates a single person by id', async () => {
+    let request: Record<string, unknown> | undefined;
+    const client = createCoreApiClientMock({
+      onMutation: (received) => {
+        request = received as Record<string, unknown>;
+      },
+    });
+
+    await updatePersonRecord({
+      client,
+      recordId: 'p1',
+      data: { jobTitle: 'CEO' },
+    });
+
+    expect(request).toMatchObject({
+      updatePerson: { __args: { id: 'p1', data: { jobTitle: 'CEO' } } },
+    });
+  });
+});

package/src/logic-functions/utils/aggregate-bulk-enrich-result.ts

@@ -0,0 +1,21 @@
+import { type BulkEnrichResult } from 'src/types/bulk-enrich-result';
+import { type EnrichResult } from 'src/types/enrich-result';
+
+export const aggregateBulkEnrichResult = (
+  results: EnrichResult[],
+): BulkEnrichResult => {
+  const countByStatus = (status: EnrichResult['status']): number =>
+    results.filter((result) => result.status === status).length;
+
+  const errored = countByStatus('ERROR');
+
+  return {
+    success: errored === 0,
+    total: results.length,
+    matched: countByStatus('MATCHED'),
+    notFound: countByStatus('NOT_FOUND'),
+    skipped: countByStatus('SKIPPED'),
+    errored,
+    results,
+  };
+};

package/src/logic-functions/utils/build-address.ts

@@ -0,0 +1,40 @@
+import { toText } from 'src/logic-functions/utils/to-text';
+import { parseGeo } from 'src/logic-functions/utils/parse-geo';
+import { type AddressParts } from 'src/types/address-parts';
+import { type AddressValue } from 'src/types/address-value';
+import { isDefined } from 'src/utils/is-defined';
+
+export const buildAddress = (parts: AddressParts): AddressValue | undefined => {
+  const street1 = toText(parts.street1);
+  const street2 = toText(parts.street2);
+  const city = toText(parts.city);
+  const postcode = toText(parts.postcode);
+  const state = toText(parts.state);
+  const country = toText(parts.country);
+  const { lat, lng } = parseGeo(parts.geo);
+
+  const hasAnyValue =
+    isDefined(street1) ||
+    isDefined(street2) ||
+    isDefined(city) ||
+    isDefined(postcode) ||
+    isDefined(state) ||
+    isDefined(country) ||
+    isDefined(lat) ||
+    isDefined(lng);
+
+  if (!hasAnyValue) {
+    return undefined;
+  }
+
+  return {
+    addressStreet1: street1 ?? '',
+    addressStreet2: street2 ?? '',
+    addressCity: city ?? '',
+    addressPostcode: postcode ?? '',
+    addressState: state ?? '',
+    addressCountry: country ?? '',
+    addressLat: lat,
+    addressLng: lng,
+  };
+};

package/src/logic-functions/utils/build-allowed-values.ts

@@ -0,0 +1,5 @@
+import { type SelectOptionMeta } from 'src/types/select-option-meta';
+
+export const buildAllowedValues = (
+  options: readonly SelectOptionMeta[],
+): Set<string> => new Set(options.map((option) => option.value));

package/src/logic-functions/utils/build-bulk-records-trigger.ts

@@ -0,0 +1,25 @@
+import { type WorkflowBulkRecordsTrigger } from 'src/types/workflow-bulk-records-trigger';
+
+export const buildBulkRecordsTrigger = ({
+  objectNameSingular,
+  name,
+  icon,
+}: {
+  objectNameSingular: string;
+  name: string;
+  icon: string;
+}): WorkflowBulkRecordsTrigger => ({
+  name,
+  type: 'MANUAL',
+  settings: {
+    objectType: objectNameSingular,
+    availability: {
+      type: 'BULK_RECORDS',
+      objectNameSingular,
+    },
+    outputSchema: {},
+    icon,
+    isPinned: false,
+  },
+  nextStepIds: [],
+});

package/src/logic-functions/utils/build-company-create-data.ts

@@ -0,0 +1,35 @@
+import { INDUSTRY_OPTIONS } from 'src/constants/industry-options';
+import { SIZE_OPTIONS } from 'src/constants/size-options';
+import { buildAllowedValues } from 'src/logic-functions/utils/build-allowed-values';
+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 { pickSelect } from 'src/logic-functions/utils/pick-select';
+import { sizeTransform } from 'src/logic-functions/utils/size-transform';
+import { toText } from 'src/logic-functions/utils/to-text';
+import { type PdlPersonData } from 'src/types/pdl-person-data';
+import { pruneUndefined } from 'src/utils/prune-undefined';
+
+const INDUSTRY_VALUES = buildAllowedValues(INDUSTRY_OPTIONS);
+const SIZE_VALUES = buildAllowedValues(SIZE_OPTIONS);
+
+export const buildCompanyCreateData = (
+  personData: PdlPersonData,
+): Record<string, unknown> =>
+  pruneUndefined<unknown>({
+    name: toText(personData.job_company_name),
+    domainName: buildLinks({ url: normalizeDomain(personData.job_company_website) }),
+    linkedinLink: buildLinks({
+      url: normalizeLinkedinUrl(personData.job_company_linkedin_url),
+    }),
+    pdlId: toText(personData.job_company_id),
+    pdlIndustry: pickSelect({
+      raw: personData.job_company_industry,
+      allowedValues: INDUSTRY_VALUES,
+    }),
+    pdlSizeRange: pickSelect({
+      raw: personData.job_company_size,
+      allowedValues: SIZE_VALUES,
+      transform: sizeTransform,
+    }),
+  });

package/src/logic-functions/utils/build-company-match-keys.ts

@@ -0,0 +1,16 @@
+import { normalizeDomain } from 'src/logic-functions/utils/normalize-domain';
+import { normalizeLinkedinUrl } from 'src/logic-functions/utils/normalize-linkedin-url';
+import { toText } from 'src/logic-functions/utils/to-text';
+import { type CompanyMatchKeys } from 'src/types/company-match-keys';
+import { type PdlPersonData } from 'src/types/pdl-person-data';
+import { pruneUndefined } from 'src/utils/prune-undefined';
+
+export const buildCompanyMatchKeys = (
+  personData: PdlPersonData,
+): CompanyMatchKeys =>
+  pruneUndefined({
+    pdlId: toText(personData.job_company_id),
+    website: normalizeDomain(personData.job_company_website),
+    linkedinUrl: normalizeLinkedinUrl(personData.job_company_linkedin_url),
+    name: toText(personData.job_company_name),
+  });

package/src/logic-functions/utils/build-company-matched-data.ts

@@ -0,0 +1,56 @@
+import { isEmptyAddress } from 'src/logic-functions/utils/is-empty-address';
+import { isEmptyLinks } from 'src/logic-functions/utils/is-empty-links';
+import { isEmptyText } from 'src/logic-functions/utils/is-empty-text';
+import { mapCompany } from 'src/logic-functions/utils/map-company';
+import { pickWritableStandard } from 'src/logic-functions/utils/pick-writable-standard';
+import { type CompanyNode } from 'src/types/company-node';
+import { type PdlCompanyData } from 'src/types/pdl-company-data';
+import { pruneUndefined } from 'src/utils/prune-undefined';
+
+const COMPANY_EMPTY_CHECKS = {
+  name: isEmptyText,
+  domainName: isEmptyLinks,
+  linkedinLink: isEmptyLinks,
+  address: isEmptyAddress,
+};
+
+export const buildCompanyMatchedData = async ({
+  node,
+  outcome,
+  enrichedAt,
+  overrideExistingValues,
+  shouldPersist,
+}: {
+  node: CompanyNode;
+  outcome: { data: PdlCompanyData };
+  enrichedAt: string;
+  overrideExistingValues: boolean;
+  shouldPersist: boolean;
+}): Promise<{
+  mappedData: Record<string, unknown>;
+  persistData: Record<string, unknown>;
+}> => {
+  const mapped = mapCompany(outcome.data);
+  const mappedData = pruneUndefined({ ...mapped.standard, ...mapped.pdl });
+
+  if (!shouldPersist) {
+    return { mappedData, persistData: {} };
+  }
+
+  const writableStandard = pickWritableStandard({
+    standard: mapped.standard,
+    current: node as unknown as Record<string, unknown>,
+    emptyChecks: COMPANY_EMPTY_CHECKS,
+    overrideExistingValues,
+  });
+
+  const persistData = pruneUndefined({
+    ...writableStandard,
+    ...mapped.pdl,
+    pdlRawPayload: outcome.data,
+    pdlLastEnrichedAt: enrichedAt,
+    pdlEnrichmentStatus: 'MATCHED',
+  });
+
+  return { mappedData, persistData };
+};

package/src/logic-functions/utils/build-currency-from-usd.ts

@@ -0,0 +1,16 @@
+import { isNumber } from '@sniptt/guards';
+
+import { type CurrencyValue } from 'src/types/currency-value';
+
+export const buildCurrencyFromUsd = (
+  amount: unknown,
+): CurrencyValue | undefined => {
+  if (!isNumber(amount) || !Number.isFinite(amount)) {
+    return undefined;
+  }
+
+  return {
+    amountMicros: Math.round(amount * 1_000_000),
+    currencyCode: 'USD',
+  };
+};

package/src/logic-functions/utils/build-emails.ts

@@ -0,0 +1,34 @@
+import { isNonEmptyArray } from '@sniptt/guards';
+
+import { toText } from 'src/logic-functions/utils/to-text';
+import { type EmailsValue } from 'src/types/emails-value';
+import { isDefined } from 'src/utils/is-defined';
+
+export const buildEmails = (
+  candidates: (string | null | undefined)[],
+): EmailsValue | undefined => {
+  const emails: string[] = [];
+  const seenEmailKeys = new Set<string>();
+
+  for (const candidate of candidates) {
+    const email = toText(candidate);
+    if (!isDefined(email)) {
+      continue;
+    }
+
+    const emailKey = email.toLowerCase();
+    if (!seenEmailKeys.has(emailKey)) {
+      seenEmailKeys.add(emailKey);
+      emails.push(email);
+    }
+  }
+
+  if (!isNonEmptyArray(emails)) {
+    return undefined;
+  }
+
+  return {
+    primaryEmail: emails[0],
+    additionalEmails: emails.length > 1 ? emails.slice(1) : null,
+  };
+};

package/src/logic-functions/utils/build-error-result.ts

@@ -0,0 +1,18 @@
+import { type EnrichResult } from 'src/types/enrich-result';
+
+export const ENRICHMENT_FAILED_MESSAGE = 'People Data Labs enrichment failed.';
+
+export const buildErrorResult = ({
+  recordId,
+  error,
+}: {
+  recordId: string;
+  error: string;
+}): EnrichResult => ({
+  success: false,
+  recordId,
+  status: 'ERROR',
+  updatedFields: [],
+  message: ENRICHMENT_FAILED_MESSAGE,
+  error,
+});

package/src/logic-functions/utils/build-full-name.ts

@@ -0,0 +1,38 @@
+import { capitalizeName } from 'src/logic-functions/utils/capitalize-name';
+import { toText } from 'src/logic-functions/utils/to-text';
+import { type FullNameValue } from 'src/types/full-name-value';
+import { isDefined } from 'src/utils/is-defined';
+
+const WHITESPACE_REGEX = /\s+/;
+
+export const buildFullName = ({
+  firstName,
+  lastName,
+  fullName,
+}: {
+  firstName: unknown;
+  lastName: unknown;
+  fullName: unknown;
+}): FullNameValue | undefined => {
+  const first = toText(firstName);
+  const last = toText(lastName);
+
+  if (isDefined(first) || isDefined(last)) {
+    return {
+      firstName: isDefined(first) ? capitalizeName(first) : '',
+      lastName: isDefined(last) ? capitalizeName(last) : '',
+    };
+  }
+
+  const full = toText(fullName);
+  if (!isDefined(full)) {
+    return undefined;
+  }
+
+  const [firstNameToken, ...remainingNameTokens] = full.split(WHITESPACE_REGEX);
+
+  return {
+    firstName: capitalizeName(firstNameToken),
+    lastName: capitalizeName(remainingNameTokens.join(' ')),
+  };
+};

package/src/logic-functions/utils/build-links.ts

@@ -0,0 +1,23 @@
+import { toText } from 'src/logic-functions/utils/to-text';
+import { type LinksValue } from 'src/types/links-value';
+import { isDefined } from 'src/utils/is-defined';
+
+export const buildLinks = ({
+  url,
+  label,
+}: {
+  url: unknown;
+  label?: unknown;
+}): LinksValue | undefined => {
+  const primaryLinkUrl = toText(url);
+
+  if (!isDefined(primaryLinkUrl)) {
+    return undefined;
+  }
+
+  return {
+    primaryLinkUrl,
+    primaryLinkLabel: toText(label) ?? '',
+    secondaryLinks: null,
+  };
+};

package/src/logic-functions/utils/build-logic-function-step.ts

@@ -0,0 +1,30 @@
+import { type WorkflowLogicFunctionStep } from 'src/types/workflow-logic-function-step';
+
+export const buildLogicFunctionStep = ({
+  id,
+  name,
+  logicFunctionId,
+  logicFunctionInput,
+}: {
+  id: string;
+  name: string;
+  logicFunctionId: string;
+  logicFunctionInput: Record<string, unknown>;
+}): WorkflowLogicFunctionStep => ({
+  id,
+  name,
+  type: 'LOGIC_FUNCTION',
+  valid: true,
+  settings: {
+    input: {
+      logicFunctionId,
+      logicFunctionInput,
+    },
+    outputSchema: {},
+    errorHandlingOptions: {
+      retryOnFailure: { value: false },
+      continueOnFailure: { value: false },
+    },
+  },
+  nextStepIds: [],
+});

package/src/logic-functions/utils/build-matched-result.ts

@@ -0,0 +1,21 @@
+import { type EnrichResult } from 'src/types/enrich-result';
+
+export const buildMatchedResult = ({
+  recordId,
+  updatedFields,
+  data,
+}: {
+  recordId: string;
+  updatedFields: string[];
+  data?: Record<string, unknown>;
+}): EnrichResult => ({
+  success: true,
+  recordId,
+  status: 'MATCHED',
+  updatedFields,
+  data,
+  message:
+    updatedFields.length > 0
+      ? `Enriched with People Data Labs (${updatedFields.length} fields).`
+      : 'Matched People Data Labs data; no fields updated.',
+});

package/src/logic-functions/utils/build-not-found-result.ts

@@ -0,0 +1,9 @@
+import { type EnrichResult } from 'src/types/enrich-result';
+
+export const buildNotFoundResult = (recordId: string): EnrichResult => ({
+  success: true,
+  recordId,
+  status: 'NOT_FOUND',
+  updatedFields: [],
+  message: 'People Data Labs returned no confident match.',
+});