@twentyhq/people-data-labs 1.0.0

package/src/types/full-name-value.ts

@@ -0,0 +1,4 @@
+export type FullNameValue = {
+  firstName: string;
+  lastName: string;
+};

package/src/types/links-value.ts

@@ -0,0 +1,5 @@
+export type LinksValue = {
+  primaryLinkUrl: string;
+  primaryLinkLabel: string;
+  secondaryLinks: null;
+};

package/src/types/mapped-record.ts

@@ -0,0 +1,4 @@
+export type MappedRecord = {
+  standard: Record<string, unknown>;
+  pdl: Record<string, unknown>;
+};

package/src/types/pdl-company-data.ts

@@ -0,0 +1,50 @@
+export type PdlCompanyData = {
+  id?: string | null;
+  name?: string | null;
+  display_name?: string | null;
+  legal_name?: string | null;
+  alternative_names?: string[] | null;
+  alternative_domains?: string[] | null;
+
+  website?: string | null;
+  linkedin_url?: string | null;
+  linkedin_id?: string | null;
+  facebook_url?: string | null;
+  twitter_url?: string | null;
+  profiles?: string[] | null;
+
+  industry?: string | null;
+  industry_v2?: string | null;
+  naics?: unknown[] | null;
+  sic?: unknown[] | null;
+  tags?: string[] | null;
+  type?: string | null;
+  ticker?: string | null;
+  mic_exchange?: string | null;
+
+  size?: string | null;
+  employee_count?: number | null;
+  employee_count_by_country?: Record<string, unknown> | null;
+  founded?: number | null;
+
+  summary?: string | null;
+  headline?: string | null;
+
+  total_funding_raised?: number | null;
+  latest_funding_stage?: string | null;
+  funding_stages?: string[] | null;
+  last_funding_date?: string | null;
+  number_funding_rounds?: number | null;
+
+  location?: {
+    street_address?: string | null;
+    address_line_2?: string | null;
+    locality?: string | null;
+    region?: string | null;
+    postal_code?: string | null;
+    country?: string | null;
+    continent?: string | null;
+    metro?: string | null;
+    geo?: string | null;
+  } | null;
+};

package/src/types/pdl-company-enrich-params.ts

@@ -0,0 +1,7 @@
+export type PdlCompanyEnrichParams = {
+  pdlId?: string;
+  website?: string;
+  profile?: string;
+  name?: string;
+  minLikelihood?: number;
+};

package/src/types/pdl-enrich-result.ts

@@ -0,0 +1,4 @@
+export type PdlEnrichResult<TData> =
+  | { outcome: 'matched'; httpStatus: number; likelihood?: number; data: TData }
+  | { outcome: 'not_found'; httpStatus: number }
+  | { outcome: 'error'; httpStatus: number; message: string };

package/src/types/pdl-person-data.ts

@@ -0,0 +1,65 @@
+export type PdlPersonData = {
+  id?: string | null;
+  full_name?: string | null;
+  first_name?: string | null;
+  last_name?: string | null;
+  name_aliases?: string[] | null;
+
+  work_email?: string | null;
+  personal_emails?: string[] | null;
+  emails?: ({ address?: string | null } | string)[] | null;
+  recommended_personal_email?: string | null;
+
+  mobile_phone?: string | null;
+  phone_numbers?: string[] | null;
+
+  job_title?: string | null;
+  job_title_role?: string | null;
+  job_title_sub_role?: string | null;
+  job_title_class?: string | null;
+  job_title_levels?: string[] | null;
+  job_onet_code?: string | null;
+  job_summary?: string | null;
+  job_start_date?: string | null;
+  inferred_years_experience?: number | null;
+  inferred_salary?: string | null;
+  industry?: string | null;
+
+  job_company_id?: string | null;
+  job_company_name?: string | null;
+  job_company_website?: string | null;
+  job_company_linkedin_url?: string | null;
+  job_company_industry?: string | null;
+  job_company_size?: string | null;
+
+  linkedin_url?: string | null;
+  linkedin_username?: string | null;
+  linkedin_connections?: number | null;
+  facebook_url?: string | null;
+  twitter_url?: string | null;
+  github_url?: string | null;
+
+  headline?: string | null;
+  summary?: string | null;
+  skills?: string[] | null;
+  interests?: string[] | null;
+  experience?: unknown[] | null;
+  education?: unknown[] | null;
+  certifications?: unknown[] | null;
+  profiles?: unknown[] | null;
+  languages?: unknown[] | null;
+
+  sex?: string | null;
+  birth_year?: number | null;
+  birth_date?: string | null;
+
+  location_name?: string | null;
+  location_street_address?: string | null;
+  location_address_line_2?: string | null;
+  location_locality?: string | null;
+  location_region?: string | null;
+  location_postal_code?: string | null;
+  location_country?: string | null;
+  location_metro?: string | null;
+  location_geo?: string | null;
+};

package/src/types/pdl-person-enrich-params.ts

@@ -0,0 +1,8 @@
+export type PdlPersonEnrichParams = {
+  pdlId?: string;
+  profile?: string;
+  email?: string;
+  name?: string;
+  company?: string;
+  minLikelihood?: number;
+};

package/src/types/person-node.ts

@@ -0,0 +1,11 @@
+export type PersonNode = {
+  id: string;
+  name?: { firstName?: string | null; lastName?: string | null } | null;
+  emails?: { primaryEmail?: string | null } | null;
+  phones?: { primaryPhoneNumber?: string | null } | null;
+  jobTitle?: string | null;
+  linkedinLink?: { primaryLinkUrl?: string | null } | null;
+  company?: { id?: string | null; name?: string | null } | null;
+  pdlId?: string | null;
+  pdlLastEnrichedAt?: string | null;
+};

package/src/types/phones-value.ts

@@ -0,0 +1,12 @@
+export type AdditionalPhone = {
+  number: string;
+  countryCode: string;
+  callingCode: string;
+};
+
+export type PhonesValue = {
+  primaryPhoneNumber: string;
+  primaryPhoneCountryCode: string;
+  primaryPhoneCallingCode: string;
+  additionalPhones: AdditionalPhone[] | null;
+};

package/src/types/post-install-result.ts

@@ -0,0 +1,5 @@
+import { type SeedEnrichmentWorkflowResult } from 'src/types/seed-enrichment-workflow-result';
+
+export type PostInstallResult = {
+  seededWorkflows: SeedEnrichmentWorkflowResult[];
+};

package/src/types/seed-enrichment-workflow-result.ts

@@ -0,0 +1,7 @@
+export type SeedEnrichmentWorkflowResult = {
+  objectNameSingular: string;
+  workflowName: string;
+  status: 'created' | 'skipped' | 'failed';
+  workflowId?: string;
+  error?: string;
+};

package/src/types/select-option-meta.ts

@@ -0,0 +1,9 @@
+import { type TagColor } from 'src/types/tag-color';
+
+export type SelectOptionMeta = {
+  key: string;
+  value: string;
+  label: string;
+  color: TagColor;
+  position: number;
+};

package/src/types/single-enrich-input.ts

@@ -0,0 +1,7 @@
+import { type UpdateFieldsOption } from 'src/types/update-fields-option';
+
+export type SingleEnrichInput = {
+  recordId?: string;
+  updateFields?: UpdateFieldsOption;
+  minLikelihood?: number;
+};

package/src/types/tag-color.ts

@@ -0,0 +1,26 @@
+export type TagColor =
+  | 'red'
+  | 'ruby'
+  | 'crimson'
+  | 'tomato'
+  | 'orange'
+  | 'amber'
+  | 'yellow'
+  | 'lime'
+  | 'grass'
+  | 'green'
+  | 'jade'
+  | 'mint'
+  | 'turquoise'
+  | 'cyan'
+  | 'sky'
+  | 'blue'
+  | 'iris'
+  | 'violet'
+  | 'purple'
+  | 'plum'
+  | 'pink'
+  | 'bronze'
+  | 'gold'
+  | 'brown'
+  | 'gray';

package/src/types/update-fields-option.ts

@@ -0,0 +1,4 @@
+export type UpdateFieldsOption =
+  | 'Yes and overwrite'
+  | "Yes and don't overwrite"
+  | 'No';

package/src/types/workflow-bulk-records-trigger.ts

@@ -0,0 +1,15 @@
+export type WorkflowBulkRecordsTrigger = {
+  name: string;
+  type: 'MANUAL';
+  settings: {
+    objectType: string;
+    availability: {
+      type: 'BULK_RECORDS';
+      objectNameSingular: string;
+    };
+    outputSchema: Record<string, never>;
+    icon: string;
+    isPinned: boolean;
+  };
+  nextStepIds: string[];
+};

package/src/types/workflow-logic-function-step.ts

@@ -0,0 +1,18 @@
+export type WorkflowLogicFunctionStep = {
+  id: string;
+  name: string;
+  type: 'LOGIC_FUNCTION';
+  valid: boolean;
+  settings: {
+    input: {
+      logicFunctionId: string;
+      logicFunctionInput: Record<string, unknown>;
+    };
+    outputSchema: Record<string, never>;
+    errorHandlingOptions: {
+      retryOnFailure: { value: boolean };
+      continueOnFailure: { value: boolean };
+    };
+  };
+  nextStepIds: string[];
+};

package/src/utils/__tests__/build-select-options.spec.ts

@@ -0,0 +1,20 @@
+import { describe, expect, it } from 'vitest';
+
+import { buildSelectOptions } from 'src/utils/build-select-options';
+
+describe('buildSelectOptions', () => {
+  it('attaches the universalIdentifier to each option by key', () => {
+    const options = buildSelectOptions({
+      meta: [
+        { key: 'a', value: 'A', label: 'Option A', color: 'blue', position: 0 },
+        { key: 'b', value: 'B', label: 'Option B', color: 'red', position: 1 },
+      ],
+      ids: { a: 'id-a', b: 'id-b' },
+    });
+
+    expect(options).toEqual([
+      { id: 'id-a', value: 'A', label: 'Option A', color: 'blue', position: 0 },
+      { id: 'id-b', value: 'B', label: 'Option B', color: 'red', position: 1 },
+    ]);
+  });
+});

package/src/utils/__tests__/is-defined.spec.ts

@@ -0,0 +1,16 @@
+import { describe, expect, it } from 'vitest';
+
+import { isDefined } from 'src/utils/is-defined';
+
+describe('isDefined', () => {
+  it('is true for defined values, including falsy ones', () => {
+    expect(isDefined(0)).toBe(true);
+    expect(isDefined('')).toBe(true);
+    expect(isDefined(false)).toBe(true);
+  });
+
+  it('is false for null and undefined', () => {
+    expect(isDefined(null)).toBe(false);
+    expect(isDefined(undefined)).toBe(false);
+  });
+});

package/src/utils/__tests__/is-unique-violation-error.spec.ts

@@ -0,0 +1,71 @@
+import { describe, expect, it } from 'vitest';
+
+import { isUniqueViolationError } from 'src/utils/is-unique-violation-error';
+
+describe('isUniqueViolationError', () => {
+  it('detects common unique-violation phrasings (case-insensitive)', () => {
+    expect(
+      isUniqueViolationError(
+        new Error('duplicate key value violates unique constraint'),
+      ),
+    ).toBe(true);
+    expect(isUniqueViolationError(new Error('Record already exists'))).toBe(
+      true,
+    );
+    expect(isUniqueViolationError({ message: 'Uniqueness violated' })).toBe(
+      true,
+    );
+    expect(isUniqueViolationError('VIOLATES UNIQUE index')).toBe(true);
+  });
+
+  it('returns false for unrelated errors and non-error values', () => {
+    expect(isUniqueViolationError(new Error('network down'))).toBe(false);
+    expect(isUniqueViolationError(null)).toBe(false);
+    expect(isUniqueViolationError(undefined)).toBe(false);
+    expect(isUniqueViolationError(42)).toBe(false);
+  });
+
+  it("detects Twenty's user-friendly duplicate phrasing in graphQLErrors", () => {
+    expect(
+      isUniqueViolationError({
+        message: 'Response not successful',
+        graphQLErrors: [
+          {
+            message: 'A duplicate entry was detected',
+            extensions: {
+              code: 'BAD_USER_INPUT',
+              userFriendlyMessage:
+                'This domain name value is already in use. Please check your data.',
+            },
+          },
+        ],
+      }),
+    ).toBe(true);
+  });
+
+  it('detects the structured DUPLICATE_ENTRY_DETECTED extensions code', () => {
+    expect(
+      isUniqueViolationError({
+        message: 'whatever',
+        extensions: { code: 'DUPLICATE_ENTRY_DETECTED' },
+      }),
+    ).toBe(true);
+  });
+
+  it('does not throw on a circular error object', () => {
+    const circular: Record<string, unknown> = { message: 'boom' };
+    circular.self = circular;
+
+    expect(() => isUniqueViolationError(circular)).not.toThrow();
+    expect(isUniqueViolationError(circular)).toBe(false);
+  });
+
+  it('finds the duplicate signal even on a circular error object', () => {
+    const circular: Record<string, unknown> = {
+      message: 'duplicate key value',
+    };
+    circular.self = circular;
+
+    expect(isUniqueViolationError(circular)).toBe(true);
+  });
+});

package/src/utils/__tests__/normalize-enum-value.spec.ts

@@ -0,0 +1,28 @@
+import { describe, expect, it } from 'vitest';
+
+import { normalizeEnumValue } from 'src/utils/normalize-enum-value';
+
+describe('normalizeEnumValue', () => {
+  it('uppercases a simple value', () => {
+    expect(normalizeEnumValue('engineering')).toBe('ENGINEERING');
+  });
+
+  it('collapses spaces into a single underscore', () => {
+    expect(normalizeEnumValue('computer software')).toBe('COMPUTER_SOFTWARE');
+  });
+
+  it('collapses punctuation runs into a single underscore', () => {
+    expect(normalizeEnumValue('airlines/aviation')).toBe('AIRLINES_AVIATION');
+    expect(normalizeEnumValue('san francisco, california')).toBe(
+      'SAN_FRANCISCO_CALIFORNIA',
+    );
+  });
+
+  it('strips diacritics', () => {
+    expect(normalizeEnumValue('Montréal')).toBe('MONTREAL');
+  });
+
+  it('prefixes a leading digit with an underscore', () => {
+    expect(normalizeEnumValue('3m')).toBe('_3M');
+  });
+});

package/src/utils/__tests__/prune-undefined.spec.ts

@@ -0,0 +1,22 @@
+import { describe, expect, it } from 'vitest';
+
+import { pruneUndefined } from 'src/utils/prune-undefined';
+
+describe('pruneUndefined', () => {
+  it('removes keys whose value is undefined', () => {
+    expect(pruneUndefined({ a: 1, b: undefined, c: 3 })).toEqual({ a: 1, c: 3 });
+  });
+
+  it('keeps falsy values that are not undefined', () => {
+    expect(pruneUndefined({ a: 0, b: '', c: null, d: false })).toEqual({
+      a: 0,
+      b: '',
+      c: null,
+      d: false,
+    });
+  });
+
+  it('returns an empty object when every value is undefined', () => {
+    expect(pruneUndefined({ a: undefined, b: undefined })).toEqual({});
+  });
+});

package/src/utils/__tests__/strip-separators.spec.ts

@@ -0,0 +1,13 @@
+import { describe, expect, it } from 'vitest';
+
+import { stripSeparators } from 'src/utils/strip-separators';
+
+describe('stripSeparators', () => {
+  it('removes spaces and commas', () => {
+    expect(stripSeparators('45,000 - 55,000')).toBe('45000-55000');
+  });
+
+  it('leaves a value without separators unchanged', () => {
+    expect(stripSeparators('1-10')).toBe('1-10');
+  });
+});

package/src/utils/__tests__/to-error-message.spec.ts

@@ -0,0 +1,13 @@
+import { describe, expect, it } from 'vitest';
+
+import { toErrorMessage } from 'src/utils/to-error-message';
+
+describe('toErrorMessage', () => {
+  it('returns the message of an Error', () => {
+    expect(toErrorMessage(new Error('boom'))).toBe('boom');
+  });
+
+  it('stringifies a non-Error value', () => {
+    expect(toErrorMessage('oops')).toBe('oops');
+  });
+});

package/src/utils/build-select-options.ts

@@ -0,0 +1,16 @@
+import { type SelectOptionMeta } from 'src/types/select-option-meta';
+
+export const buildSelectOptions = ({
+  meta,
+  ids,
+}: {
+  meta: readonly SelectOptionMeta[];
+  ids: Record<string, string>;
+}) =>
+  meta.map(({ key, value, label, color, position }) => ({
+    id: ids[key],
+    value,
+    label,
+    color,
+    position,
+  }));

package/src/utils/is-defined.ts

@@ -0,0 +1,5 @@
+import { isNull, isUndefined } from '@sniptt/guards';
+
+export const isDefined = <T>(
+  value: T | null | undefined,
+): value is NonNullable<T> => !isUndefined(value) && !isNull(value);

package/src/utils/is-unique-violation-error.ts

@@ -0,0 +1,74 @@
+import { isObject } from '@sniptt/guards';
+
+import { isDefined } from 'src/utils/is-defined';
+
+const DUPLICATE_VIOLATION_PHRASES = [
+  'duplicate',
+  'unique constraint',
+  'uniqueness',
+  'already exists',
+  'is already in use',
+  'violates unique',
+  'duplicate_entry_detected',
+];
+
+const MAX_ERROR_TRAVERSAL_DEPTH = 4;
+
+const stringifyWithoutThrowingOnCycles = (value: unknown): string => {
+  try {
+    return JSON.stringify(value) ?? '';
+  } catch {
+    return '';
+  }
+};
+
+const collectErrorText = (error: unknown, depth = 0): string => {
+  if (!isDefined(error) || depth > MAX_ERROR_TRAVERSAL_DEPTH) {
+    return '';
+  }
+  if (typeof error === 'string') {
+    return error;
+  }
+  if (typeof error !== 'object') {
+    return String(error);
+  }
+
+  const errorObject = error as Record<string, unknown>;
+  const textFragments: string[] = [];
+
+  if (typeof errorObject.message === 'string') {
+    textFragments.push(errorObject.message);
+  }
+
+  if (Array.isArray(errorObject.graphQLErrors)) {
+    for (const graphQLError of errorObject.graphQLErrors) {
+      textFragments.push(collectErrorText(graphQLError, depth + 1));
+    }
+  }
+
+  if (isObject(errorObject.extensions)) {
+    const extensions = errorObject.extensions as Record<string, unknown>;
+    if (typeof extensions.code === 'string') {
+      textFragments.push(extensions.code);
+    }
+    if (typeof extensions.userFriendlyMessage === 'string') {
+      textFragments.push(extensions.userFriendlyMessage);
+    }
+  }
+
+  if (isDefined(errorObject.cause)) {
+    textFragments.push(collectErrorText(errorObject.cause, depth + 1));
+  }
+
+  textFragments.push(stringifyWithoutThrowingOnCycles(error));
+
+  return textFragments.join(' ');
+};
+
+export const isUniqueViolationError = (error: unknown): boolean => {
+  const lowerCaseErrorText = collectErrorText(error).toLowerCase();
+
+  return DUPLICATE_VIOLATION_PHRASES.some((phrase) =>
+    lowerCaseErrorText.includes(phrase),
+  );
+};

package/src/utils/normalize-enum-value.ts

@@ -0,0 +1,15 @@
+const DIACRITICS_REGEX = new RegExp('[\\u0300-\\u036f]', 'g');
+const NON_ALPHANUMERIC_RUN_REGEX = /[^A-Z0-9]+/g;
+const LEADING_OR_TRAILING_UNDERSCORE_REGEX = /^_+|_+$/g;
+const LEADING_DIGIT_REGEX = /^(\d)/;
+
+export const normalizeEnumValue = (rawEnumValue: string): string => {
+  const withoutDiacritics = rawEnumValue
+    .normalize('NFKD')
+    .replace(DIACRITICS_REGEX, '');
+  const upperCased = withoutDiacritics.toUpperCase();
+  const underscored = upperCased.replace(NON_ALPHANUMERIC_RUN_REGEX, '_');
+  const trimmed = underscored.replace(LEADING_OR_TRAILING_UNDERSCORE_REGEX, '');
+
+  return trimmed.replace(LEADING_DIGIT_REGEX, '_$1');
+};

package/src/utils/prune-undefined.ts

@@ -0,0 +1,15 @@
+import { isUndefined } from '@sniptt/guards';
+
+export const pruneUndefined = <TValue>(
+  record: Record<string, TValue | undefined>,
+): Record<string, TValue> => {
+  const prunedRecord: Record<string, TValue> = {};
+
+  for (const [key, value] of Object.entries(record)) {
+    if (!isUndefined(value)) {
+      prunedRecord[key] = value;
+    }
+  }
+
+  return prunedRecord;
+};

package/src/utils/strip-separators.ts

@@ -0,0 +1,4 @@
+const WHITESPACE_AND_COMMA_REGEX = /[\s,]/g;
+
+export const stripSeparators = (rawValue: string): string =>
+  rawValue.replace(WHITESPACE_AND_COMMA_REGEX, '');

package/src/utils/to-error-message.ts

@@ -0,0 +1,2 @@
+export const toErrorMessage = (error: unknown): string =>
+  error instanceof Error ? error.message : String(error);