@twentyhq/people-data-labs 1.0.0

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

@@ -0,0 +1,81 @@
+import { describe, expect, it } from 'vitest';
+
+import { PDL_PERSON_DATA_MOCK } from 'src/logic-functions/__mocks__/pdl-person-data.mock';
+import { mapPerson } from 'src/logic-functions/utils/map-person';
+
+describe('mapPerson', () => {
+  it('maps standard fields', () => {
+    const { standard } = mapPerson(PDL_PERSON_DATA_MOCK);
+
+    expect(standard.name).toEqual({ firstName: 'Jane', lastName: 'Doe' });
+    expect(standard.emails).toEqual({
+      primaryEmail: 'jane.doe@acme.com',
+      additionalEmails: ['jane@personal.com'],
+    });
+    expect(standard.jobTitle).toBe('Chief Executive Officer');
+    expect(standard.linkedinLink).toMatchObject({
+      primaryLinkUrl: 'https://linkedin.com/in/janedoe',
+    });
+  });
+
+  it('maps pdl scalar, select and number fields', () => {
+    const { pdl } = mapPerson(PDL_PERSON_DATA_MOCK);
+
+    expect(pdl.pdlId).toBe('pdl-person-1');
+    expect(pdl.pdlJobRole).toBe('ENGINEERING');
+    expect(pdl.pdlIndustry).toBe('ACCOUNTING');
+    expect(pdl.pdlInferredSalary).toBe('FROM_45000_TO_55000');
+  });
+
+  it('does not map company attributes onto the person', () => {
+    const { pdl } = mapPerson(PDL_PERSON_DATA_MOCK);
+
+    expect('pdlJobCompanyName' in pdl).toBe(false);
+    expect('pdlJobCompanySize' in pdl).toBe(false);
+  });
+
+  it('drops unknown multi-select values', () => {
+    const { pdl } = mapPerson(PDL_PERSON_DATA_MOCK);
+
+    expect(pdl.pdlSeniority).toEqual(['CXO']);
+  });
+
+  it('dedupes array fields and passes raw json through', () => {
+    const { pdl } = mapPerson(PDL_PERSON_DATA_MOCK);
+
+    expect(pdl.pdlSkills).toEqual(['leadership', 'strategy']);
+    expect(pdl.pdlExperience).toEqual([{ company: { name: 'Acme' } }]);
+  });
+
+  it('expands partial dates and builds the address with addressPostcode', () => {
+    const { pdl } = mapPerson(PDL_PERSON_DATA_MOCK);
+
+    expect(pdl.pdlBirthDate).toBe('1990-01-01');
+    expect(pdl.pdlLocation).toMatchObject({
+      addressCity: 'San Francisco',
+      addressState: 'California',
+      addressPostcode: '94107',
+      addressCountry: 'United States',
+    });
+  });
+
+  it('omits fields PDL did not return', () => {
+    const { pdl } = mapPerson(PDL_PERSON_DATA_MOCK);
+
+    expect('pdlSex' in pdl).toBe(false);
+  });
+
+  it('tolerates PDL returning presence-flag booleans for email and phone fields', () => {
+    const { standard } = mapPerson({
+      ...PDL_PERSON_DATA_MOCK,
+      emails: true as never,
+      personal_emails: true as never,
+      phone_numbers: true as never,
+    });
+
+    expect(standard.emails).toEqual({
+      primaryEmail: 'jane.doe@acme.com',
+      additionalEmails: null,
+    });
+  });
+});

package/src/logic-functions/utils/__tests__/normalize-domain.spec.ts

@@ -0,0 +1,19 @@
+import { describe, expect, it } from 'vitest';
+
+import { normalizeDomain } from 'src/logic-functions/utils/normalize-domain';
+
+describe('normalizeDomain', () => {
+  it('reduces variants to the same bare host', () => {
+    expect(normalizeDomain('acme.com')).toBe('acme.com');
+    expect(normalizeDomain('https://www.Acme.com/')).toBe('acme.com');
+    expect(normalizeDomain('HTTP://acme.com/careers')).toBe('acme.com');
+    expect(normalizeDomain('www.acme.com')).toBe('acme.com');
+  });
+
+  it('returns undefined for blank or missing values', () => {
+    expect(normalizeDomain('')).toBeUndefined();
+    expect(normalizeDomain('   ')).toBeUndefined();
+    expect(normalizeDomain(null)).toBeUndefined();
+    expect(normalizeDomain(undefined)).toBeUndefined();
+  });
+});

package/src/logic-functions/utils/__tests__/normalize-linkedin-url.spec.ts

@@ -0,0 +1,22 @@
+import { describe, expect, it } from 'vitest';
+
+import { normalizeLinkedinUrl } from 'src/logic-functions/utils/normalize-linkedin-url';
+
+describe('normalizeLinkedinUrl', () => {
+  it('canonicalizes scheme/www/trailing slash while keeping the path', () => {
+    expect(normalizeLinkedinUrl('linkedin.com/company/acme')).toBe(
+      'linkedin.com/company/acme',
+    );
+    expect(normalizeLinkedinUrl('https://www.linkedin.com/company/acme/')).toBe(
+      'linkedin.com/company/acme',
+    );
+    expect(normalizeLinkedinUrl('HTTPS://LinkedIn.com/company/Acme')).toBe(
+      'linkedin.com/company/acme',
+    );
+  });
+
+  it('returns undefined for blank or missing values', () => {
+    expect(normalizeLinkedinUrl('')).toBeUndefined();
+    expect(normalizeLinkedinUrl(null)).toBeUndefined();
+  });
+});

package/src/logic-functions/utils/__tests__/now-iso.spec.ts

@@ -0,0 +1,9 @@
+import { describe, expect, it } from 'vitest';
+
+import { nowIso } from 'src/logic-functions/utils/now-iso';
+
+describe('nowIso', () => {
+  it('returns an ISO-8601 timestamp string', () => {
+    expect(nowIso()).toMatch(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}/);
+  });
+});

package/src/logic-functions/utils/__tests__/parse-geo.spec.ts

@@ -0,0 +1,21 @@
+import { describe, expect, it } from 'vitest';
+
+import { parseGeo } from 'src/logic-functions/utils/parse-geo';
+
+describe('parseGeo', () => {
+  it('parses a "lat,lng" string', () => {
+    expect(parseGeo('37.77,-122.41')).toEqual({ lat: 37.77, lng: -122.41 });
+  });
+
+  it('returns nulls for missing or malformed input', () => {
+    expect(parseGeo(undefined)).toEqual({ lat: null, lng: null });
+    expect(parseGeo('not-a-geo')).toEqual({ lat: null, lng: null });
+  });
+
+  it('rejects a single value, extra components, or out-of-range coordinates', () => {
+    expect(parseGeo('37.77')).toEqual({ lat: null, lng: null });
+    expect(parseGeo('37.77,-122.41,5')).toEqual({ lat: null, lng: null });
+    expect(parseGeo('200,0')).toEqual({ lat: null, lng: null });
+    expect(parseGeo('0,200')).toEqual({ lat: null, lng: null });
+  });
+});

package/src/logic-functions/utils/__tests__/parse-partial-date.spec.ts

@@ -0,0 +1,29 @@
+import { describe, expect, it } from 'vitest';
+
+import { parsePartialDate } from 'src/logic-functions/utils/parse-partial-date';
+
+describe('parsePartialDate', () => {
+  it('expands a year to a full date', () => {
+    expect(parsePartialDate('1990')).toBe('1990-01-01');
+  });
+
+  it('expands a year-month to a full date', () => {
+    expect(parsePartialDate('2020-05')).toBe('2020-05-01');
+  });
+
+  it('keeps a full date', () => {
+    expect(parsePartialDate('2020-05-17')).toBe('2020-05-17');
+  });
+
+  it('returns undefined for an unparseable value', () => {
+    expect(parsePartialDate('not-a-date')).toBeUndefined();
+    expect(parsePartialDate(undefined)).toBeUndefined();
+  });
+
+  it('rejects out-of-range or non-existent calendar dates', () => {
+    expect(parsePartialDate('2020-13')).toBeUndefined();
+    expect(parsePartialDate('2020-00-01')).toBeUndefined();
+    expect(parsePartialDate('1990-02-31')).toBeUndefined();
+    expect(parsePartialDate('2020-04-31')).toBeUndefined();
+  });
+});

package/src/logic-functions/utils/__tests__/parse-pdl-item.spec.ts

@@ -0,0 +1,88 @@
+import { describe, expect, it } from 'vitest';
+
+import { parsePdlItem } from 'src/logic-functions/utils/parse-pdl-item';
+
+describe('parsePdlItem', () => {
+  it('maps a 200 item to a matched outcome with data and likelihood', () => {
+    expect(
+      parsePdlItem({ item: { status: 200, likelihood: 8, data: { id: 'x' } } }),
+    ).toEqual({
+      outcome: 'matched',
+      httpStatus: 200,
+      likelihood: 8,
+      data: { id: 'x' },
+    });
+  });
+
+  it('defaults a missing status to 200 and matches when data is present', () => {
+    expect(parsePdlItem({ item: { data: { id: 'x' } } })).toEqual({
+      outcome: 'matched',
+      httpStatus: 200,
+      likelihood: undefined,
+      data: { id: 'x' },
+    });
+  });
+
+  it('matches a 200 item whose record fields are at the top level (company bulk shape)', () => {
+    expect(
+      parsePdlItem({
+        item: { status: 200, likelihood: 6, id: 'x', name: 'Acme' },
+      }),
+    ).toEqual({
+      outcome: 'matched',
+      httpStatus: 200,
+      likelihood: 6,
+      data: { id: 'x', name: 'Acme' },
+    });
+  });
+
+  it('treats a 200 item carrying only the envelope as not_found', () => {
+    expect(parsePdlItem({ item: { status: 200, likelihood: 6 } })).toEqual({
+      outcome: 'not_found',
+      httpStatus: 200,
+    });
+  });
+
+  it('rejects a match whose likelihood is below the requested threshold', () => {
+    expect(
+      parsePdlItem({
+        item: { status: 200, likelihood: 3, data: { id: 'x' } },
+        requestedMinLikelihood: 6,
+      }),
+    ).toEqual({ outcome: 'not_found', httpStatus: 200 });
+  });
+
+  it('keeps a match whose likelihood meets the requested threshold', () => {
+    expect(
+      parsePdlItem({
+        item: { status: 200, likelihood: 6, data: { id: 'x' } },
+        requestedMinLikelihood: 6,
+      }),
+    ).toMatchObject({ outcome: 'matched', likelihood: 6 });
+  });
+
+  it('maps a 404 item to not_found', () => {
+    expect(parsePdlItem({ item: { status: 404 } })).toEqual({
+      outcome: 'not_found',
+      httpStatus: 404,
+    });
+  });
+
+  it('maps a non-2xx item to an error with the PDL message', () => {
+    expect(
+      parsePdlItem({ item: { status: 500, error: { message: 'boom' } } }),
+    ).toEqual({
+      outcome: 'error',
+      httpStatus: 500,
+      message: 'boom',
+    });
+  });
+
+  it('treats a non-object item as a malformed error', () => {
+    expect(parsePdlItem({ item: undefined })).toEqual({
+      outcome: 'error',
+      httpStatus: 0,
+      message: 'People Data Labs returned a malformed response item.',
+    });
+  });
+});

package/src/logic-functions/utils/__tests__/pick-multi-select.spec.ts

@@ -0,0 +1,28 @@
+import { describe, expect, it } from 'vitest';
+
+import { pickMultiSelect } from 'src/logic-functions/utils/pick-multi-select';
+
+const LEVELS = new Set(['CXO', 'VP', 'DIRECTOR']);
+
+describe('pickMultiSelect', () => {
+  it('keeps allowed values and drops unknown ones', () => {
+    expect(
+      pickMultiSelect({ rawValues: ['cxo', 'vp', 'unknown'], allowedValues: LEVELS }),
+    ).toEqual(['CXO', 'VP']);
+  });
+
+  it('dedupes repeated values', () => {
+    expect(
+      pickMultiSelect({ rawValues: ['cxo', 'cxo'], allowedValues: LEVELS }),
+    ).toEqual(['CXO']);
+  });
+
+  it('returns undefined for a non-array or when nothing is valid', () => {
+    expect(
+      pickMultiSelect({ rawValues: 'cxo', allowedValues: LEVELS }),
+    ).toBeUndefined();
+    expect(
+      pickMultiSelect({ rawValues: ['unknown'], allowedValues: LEVELS }),
+    ).toBeUndefined();
+  });
+});

package/src/logic-functions/utils/__tests__/pick-select.spec.ts

@@ -0,0 +1,38 @@
+import { describe, expect, it } from 'vitest';
+
+import { pickSelect } from 'src/logic-functions/utils/pick-select';
+import { sizeTransform } from 'src/logic-functions/utils/size-transform';
+
+const ROLES = new Set(['ENGINEERING', 'SALES']);
+const SIZES = new Set(['ONE_TO_TEN', 'ELEVEN_TO_FIFTY']);
+
+describe('pickSelect', () => {
+  it('normalizes and returns an allowed value', () => {
+    expect(pickSelect({ raw: 'engineering', allowedValues: ROLES })).toBe(
+      'ENGINEERING',
+    );
+  });
+
+  it('returns undefined for a value outside the option set', () => {
+    expect(
+      pickSelect({ raw: 'marketing', allowedValues: ROLES }),
+    ).toBeUndefined();
+  });
+
+  it('returns undefined for empty or non-string input', () => {
+    expect(pickSelect({ raw: '', allowedValues: ROLES })).toBeUndefined();
+    expect(
+      pickSelect({ raw: undefined, allowedValues: ROLES }),
+    ).toBeUndefined();
+  });
+
+  it('applies a custom transform before checking the option set', () => {
+    expect(
+      pickSelect({
+        raw: '1-10',
+        allowedValues: SIZES,
+        transform: sizeTransform,
+      }),
+    ).toBe('ONE_TO_TEN');
+  });
+});

package/src/logic-functions/utils/__tests__/pick-writable-standard.spec.ts

@@ -0,0 +1,37 @@
+import { describe, expect, it } from 'vitest';
+
+import { pickWritableStandard } from 'src/logic-functions/utils/pick-writable-standard';
+import { isEmptyText } from 'src/logic-functions/utils/is-empty-text';
+
+describe('pickWritableStandard', () => {
+  it('keeps a mapped field only when the current value is empty', () => {
+    const writable = pickWritableStandard({
+      standard: { name: 'Acme', jobTitle: 'CEO' },
+      current: { name: '', jobTitle: 'Existing' },
+      emptyChecks: { name: isEmptyText, jobTitle: isEmptyText },
+    });
+
+    expect(writable).toEqual({ name: 'Acme' });
+  });
+
+  it('skips fields without a registered check rather than overwriting them', () => {
+    const writable = pickWritableStandard({
+      standard: { extra: 'value' },
+      current: { extra: 'already here' },
+      emptyChecks: {},
+    });
+
+    expect(writable).toEqual({});
+  });
+
+  it('overwrites a non-empty value when overrideExistingValues is set, still skipping unregistered fields', () => {
+    const writable = pickWritableStandard({
+      standard: { name: 'Acme', extra: 'value' },
+      current: { name: 'Existing', extra: 'already here' },
+      emptyChecks: { name: isEmptyText },
+      overrideExistingValues: true,
+    });
+
+    expect(writable).toEqual({ name: 'Acme' });
+  });
+});

package/src/logic-functions/utils/__tests__/post-pdl-enrich.spec.ts

@@ -0,0 +1,192 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { postPdlBulkEnrich } from 'src/logic-functions/utils/post-pdl-enrich';
+
+type FetchResponse = {
+  status: number;
+  ok: boolean;
+  json: () => Promise<unknown>;
+};
+
+const buildResponse = (
+  status: number,
+  json: unknown,
+  jsonThrows = false,
+): FetchResponse => ({
+  status,
+  ok: status >= 200 && status < 300,
+  json: () =>
+    jsonThrows ? Promise.reject(new Error('invalid json')) : Promise.resolve(json),
+});
+
+const stubFetch = (response: FetchResponse | Error) => {
+  const fetchMock = vi.fn((_url: string, _init?: RequestInit) =>
+    response instanceof Error
+      ? Promise.reject(response)
+      : Promise.resolve(response),
+  );
+  vi.stubGlobal('fetch', fetchMock);
+
+  return fetchMock;
+};
+
+describe('postPdlBulkEnrich', () => {
+  beforeEach(() => {
+    process.env.PDL_API_KEY = 'secret-key';
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    delete process.env.PDL_API_KEY;
+  });
+
+  it('sends one request wrapping every record under requests[].params', async () => {
+    const fetchMock = stubFetch(buildResponse(200, [{ status: 200, data: {} }]));
+
+    await postPdlBulkEnrich({ path: '/person/bulk', requests: [{ email: 'a@b.com' }] });
+
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    const [url, init] = fetchMock.mock.calls[0] as [string, RequestInit];
+    expect(url).toBe('https://api.peopledatalabs.com/v5/person/bulk');
+    expect(JSON.parse(init.body as string)).toEqual({
+      requests: [{ params: { email: 'a@b.com' } }],
+    });
+  });
+
+  it('maps each response item to its aligned outcome', async () => {
+    stubFetch(
+      buildResponse(200, [
+        { status: 200, likelihood: 8, data: { id: 'a' } },
+        { status: 404 },
+        { status: 500, error: { message: 'boom' } },
+      ]),
+    );
+
+    const results = await postPdlBulkEnrich({
+      path: '/person/bulk',
+      requests: [
+        { email: 'a@b.com' },
+        { email: 'b@b.com' },
+        { email: 'c@b.com' },
+      ],
+    });
+
+    expect(results).toEqual([
+      { outcome: 'matched', httpStatus: 200, likelihood: 8, data: { id: 'a' } },
+      { outcome: 'not_found', httpStatus: 404 },
+      { outcome: 'error', httpStatus: 500, message: 'boom' },
+    ]);
+  });
+
+  it('matches a 200 company item whose fields are at the top level (no data envelope)', async () => {
+    stubFetch(
+      buildResponse(200, [{ status: 200, likelihood: 6, id: 'c1', name: 'Acme' }]),
+    );
+
+    const results = await postPdlBulkEnrich({
+      path: '/company/enrich/bulk',
+      requests: [{ name: 'Acme' }],
+    });
+
+    expect(results[0]).toEqual({
+      outcome: 'matched',
+      httpStatus: 200,
+      likelihood: 6,
+      data: { id: 'c1', name: 'Acme' },
+    });
+  });
+
+  it('reads the responses envelope when the body is not a bare array', async () => {
+    stubFetch(
+      buildResponse(200, { responses: [{ status: 200, data: { id: 'a' } }] }),
+    );
+
+    const results = await postPdlBulkEnrich({
+      path: '/person/bulk',
+      requests: [{ email: 'a@b.com' }],
+    });
+
+    expect(results[0]).toMatchObject({ outcome: 'matched', data: { id: 'a' } });
+  });
+
+  it('fails the whole batch when the result count does not match the request count', async () => {
+    stubFetch(buildResponse(200, [{ status: 200, data: { id: 'a' } }]));
+
+    const results = await postPdlBulkEnrich({
+      path: '/person/bulk',
+      requests: [{ email: 'a@b.com' }, { email: 'b@b.com' }],
+    });
+
+    expect(results).toEqual([
+      {
+        outcome: 'error',
+        httpStatus: 200,
+        message:
+          'People Data Labs returned 1 results for 2 requests (HTTP 200).',
+      },
+      {
+        outcome: 'error',
+        httpStatus: 200,
+        message:
+          'People Data Labs returned 1 results for 2 requests (HTTP 200).',
+      },
+    ]);
+  });
+
+  it('fails every record when the whole call is a non-2xx response', async () => {
+    stubFetch(buildResponse(401, { error: { message: 'unauthorized' } }));
+
+    const results = await postPdlBulkEnrich({
+      path: '/person/bulk',
+      requests: [{ email: 'a@b.com' }, { email: 'b@b.com' }],
+    });
+
+    expect(results).toEqual([
+      { outcome: 'error', httpStatus: 401, message: 'unauthorized' },
+      { outcome: 'error', httpStatus: 401, message: 'unauthorized' },
+    ]);
+  });
+
+  it('fails every record when fetch throws', async () => {
+    stubFetch(new Error('network down'));
+
+    const results = await postPdlBulkEnrich({
+      path: '/person/bulk',
+      requests: [{ email: 'a@b.com' }],
+    });
+
+    expect(results).toEqual([
+      {
+        outcome: 'error',
+        httpStatus: 0,
+        message: 'PDL request failed: network down',
+      },
+    ]);
+  });
+
+  it('fails every record on a non-JSON response', async () => {
+    stubFetch(buildResponse(200, null, true));
+
+    const results = await postPdlBulkEnrich({
+      path: '/person/bulk',
+      requests: [{ email: 'a@b.com' }],
+    });
+
+    expect(results).toEqual([
+      {
+        outcome: 'error',
+        httpStatus: 200,
+        message: 'PDL returned a non-JSON response (HTTP 200).',
+      },
+    ]);
+  });
+
+  it('returns an empty array without calling fetch for no records', async () => {
+    const fetchMock = stubFetch(buildResponse(200, []));
+
+    expect(await postPdlBulkEnrich({ path: '/person/bulk', requests: [] })).toEqual(
+      [],
+    );
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+});