@twentyhq/people-data-labs 1.0.0

package/.claude/settings.local.json

@@ -0,0 +1,7 @@
+{
+  "enabledMcpjsonServers": [
+    "postgres",
+    "playwright",
+    "context7"
+  ]
+}

package/.nvmrc

@@ -0,0 +1 @@
+24.5.0

package/.oxlintrc.json

@@ -0,0 +1,58 @@
+{
+  "$schema": "./node_modules/oxlint/configuration_schema.json",
+  "extends": ["../../.oxlintrc.base.json"],
+  "plugins": ["react", "typescript", "import", "unicorn"],
+  "categories": {
+    "correctness": "off"
+  },
+  "ignorePatterns": ["node_modules", "dist"],
+  "rules": {
+    "func-style": ["error", "declaration", { "allowArrowFunctions": true }],
+    "no-console": "off",
+    "no-control-regex": "off",
+    "no-debugger": "error",
+    "no-duplicate-imports": "error",
+    "no-undef": "off",
+    "no-unused-vars": "off",
+    "no-redeclare": "off",
+    "import/no-duplicates": "error",
+    "typescript/no-redeclare": "error",
+    "typescript/ban-ts-comment": "error",
+    "typescript/consistent-type-imports": [
+      "error",
+      {
+        "prefer": "type-imports",
+        "fixStyle": "inline-type-imports"
+      }
+    ],
+    "typescript/explicit-function-return-type": "off",
+    "typescript/explicit-module-boundary-types": "off",
+    "typescript/no-empty-object-type": [
+      "error",
+      {
+        "allowInterfaces": "with-single-extends"
+      }
+    ],
+    "typescript/no-empty-function": "off",
+    "typescript/no-explicit-any": "off",
+    "typescript/no-unused-vars": [
+      "warn",
+      {
+        "vars": "all",
+        "varsIgnorePattern": "^_",
+        "args": "after-used",
+        "argsIgnorePattern": "^_"
+      }
+    ],
+    "react/no-unescaped-entities": "off",
+    "react/prop-types": "off",
+    "react/jsx-key": "off",
+    "react/display-name": "off",
+    "react/jsx-uses-react": "off",
+    "react/react-in-jsx-scope": "off",
+    "react/jsx-no-useless-fragment": "off",
+    "react/jsx-props-no-spreading": ["error", { "explicitSpread": "ignore" }],
+    "react-hooks/rules-of-hooks": "error",
+    "react-hooks/exhaustive-deps": "warn"
+  }
+}

package/.yarnrc.yml

@@ -0,0 +1 @@
+nodeLinker: node-modules

package/README.md

@@ -0,0 +1,16 @@
+# People Data Labs
+
+**Turn a name into a full profile — enrich any Person or Company in one click.**
+
+## ✨ What you get
+
+- **+30 rich data fields** per Person and Company — seniority, skills, firmographics, funding, socials & more
+- **Run it anywhere** — from the command menu, as a workflow step, or straight from AI chat
+- **Smart matching** — finds the right profile from a LinkedIn, email, or domain, and only writes confident matches
+
+## 💳 Billing
+
+Pay only for matches, in Twenty credits — **not found and skipped records are free.**
+
+- **Person match:** $0.336
+- **Company match:** $0.12

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@twentyhq/people-data-labs",
+  "version": "1.0.0",
+  "description": "People Data Labs enrichment app for Twenty",
+  "license": "MIT",
+  "engines": {
+    "node": "^24.5.0",
+    "npm": "please-use-yarn",
+    "yarn": ">=4.0.2"
+  },
+  "keywords": [
+    "twenty-app"
+  ],
+  "packageManager": "yarn@4.13.0",
+  "scripts": {
+    "twenty": "twenty",
+    "lint": "oxlint -c .oxlintrc.json .",
+    "lint:fix": "oxlint --fix -c .oxlintrc.json .",
+    "typecheck": "tsgo --noEmit -p tsconfig.spec.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:unit": "vitest run --config vitest.unit.config.ts"
+  },
+  "devDependencies": {
+    "@types/node": "^24.7.2",
+    "@types/react": "^18.2.0",
+    "@typescript/native-preview": "^7.0.0-dev.20260116.1",
+    "oxlint": "^0.16.0",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "twenty-client-sdk": "^2.16.0",
+    "twenty-sdk": "^2.16.0",
+    "typescript": "^5.9.3",
+    "vite-tsconfig-paths": "^4.2.1",
+    "vitest": "^4.0.0"
+  }
+}

package/src/__tests__/global-setup.ts

@@ -0,0 +1,87 @@
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+
+import { appDevOnce, appUninstall } from 'twenty-sdk/cli';
+
+const APP_PATH = process.cwd();
+const CONFIG_DIR = path.join(os.homedir(), '.twenty');
+
+function validateEnv(): { apiUrl: string; apiKey: string } {
+  const apiUrl = process.env.TWENTY_API_URL;
+  const apiKey = process.env.TWENTY_API_KEY;
+
+  if (!apiUrl || !apiKey) {
+    throw new Error(
+      'TWENTY_API_URL and TWENTY_API_KEY must be set.\n' +
+        'Start a local server: yarn twenty docker:start\n' +
+        'Or set them in vitest env config.',
+    );
+  }
+
+  return { apiUrl, apiKey };
+}
+
+async function checkServer(apiUrl: string) {
+  let response: Response;
+
+  try {
+    response = await fetch(`${apiUrl}/healthz`);
+  } catch {
+    throw new Error(
+      `Twenty server is not reachable at ${apiUrl}. ` +
+        'Make sure the server is running before executing integration tests.',
+    );
+  }
+
+  if (!response.ok) {
+    throw new Error(`Server at ${apiUrl} returned ${response.status}`);
+  }
+}
+
+function writeConfig(apiUrl: string, apiKey: string) {
+  const payload = JSON.stringify(
+    {
+      remotes: {
+        local: { apiUrl, apiKey, accessToken: apiKey },
+      },
+      defaultRemote: 'local',
+    },
+    null,
+    2,
+  );
+
+  fs.mkdirSync(CONFIG_DIR, { recursive: true });
+  fs.writeFileSync(path.join(CONFIG_DIR, 'config.test.json'), payload);
+}
+
+export async function setup() {
+  const { apiUrl, apiKey } = validateEnv();
+
+  await checkServer(apiUrl);
+
+  writeConfig(apiUrl, apiKey);
+
+  await appUninstall({ appPath: APP_PATH }).catch(() => {});
+
+  const result = await appDevOnce({
+    appPath: APP_PATH,
+    onProgress: (message: string) => console.log(`[dev] ${message}`),
+  });
+
+  if (!result.success) {
+    throw new Error(
+      `Dev sync failed: ${result.error?.message ?? 'Unknown error'}`,
+    );
+  }
+}
+
+export async function teardown() {
+  const uninstallResult = await appUninstall({ appPath: APP_PATH });
+
+  if (!uninstallResult.success) {
+    console.warn(
+      `App uninstall failed: ${uninstallResult.error?.message ?? 'Unknown error'}`,
+    );
+  }
+}

package/src/__tests__/people-data-labs.integration-test.ts

@@ -0,0 +1,25 @@
+import { MetadataApiClient } from 'twenty-client-sdk/metadata';
+import { describe, expect, it } from 'vitest';
+
+import { APPLICATION_UNIVERSAL_IDENTIFIER } from 'src/constants/universal-identifiers';
+
+describe('People Data Labs app installation', () => {
+  it('should find the installed People Data Labs app in the applications list', async () => {
+    const client = new MetadataApiClient();
+
+    const result = await client.query({
+      findManyApplications: {
+        id: true,
+        name: true,
+        universalIdentifier: true,
+      },
+    });
+
+    const matchingApplication = result.findManyApplications.find(
+      (application: { universalIdentifier: string }) =>
+        application.universalIdentifier === APPLICATION_UNIVERSAL_IDENTIFIER,
+    );
+
+    expect(matchingApplication).toBeDefined();
+  });
+});

package/src/application-config.ts

@@ -0,0 +1,18 @@
+import { defineApplication } from 'twenty-sdk/define';
+
+import { APPLICATION_UNIVERSAL_IDENTIFIER } from 'src/constants/universal-identifiers';
+
+export default defineApplication({
+  universalIdentifier: APPLICATION_UNIVERSAL_IDENTIFIER,
+  displayName: 'People Data Labs',
+  description: 'Enrich People and Companies with People Data Labs data.',
+  logoUrl: 'public/people-data-labs-icon.png',
+  screenshots: ['public/gallery/cover.png'],
+  serverVariables: {
+    PDL_API_KEY: {
+      description: 'People Data Labs API key',
+      isSecret: true,
+      isRequired: true,
+    },
+  },
+});

package/src/command-menu-items/enrich-companies.ts

@@ -0,0 +1,14 @@
+import { defineCommandMenuItem, STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS } from 'twenty-sdk/define';
+import {
+  PDL_COMMAND_MENU_ITEM_UNIVERSAL_IDENTIFIERS,
+  PDL_FRONT_COMPONENT_UNIVERSAL_IDENTIFIERS
+} from 'src/constants/universal-identifiers';
+
+export default defineCommandMenuItem({
+  universalIdentifier: PDL_COMMAND_MENU_ITEM_UNIVERSAL_IDENTIFIERS.enrichCompanies,
+  availabilityObjectUniversalIdentifier: STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.company.universalIdentifier,
+  frontComponentUniversalIdentifier:
+  PDL_FRONT_COMPONENT_UNIVERSAL_IDENTIFIERS.enrichCompanies,
+  label: 'Enrich companies',
+  availabilityType: 'RECORD_SELECTION',
+});

package/src/command-menu-items/enrich-people.ts

@@ -0,0 +1,14 @@
+import { defineCommandMenuItem, STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS } from 'twenty-sdk/define';
+import {
+  PDL_COMMAND_MENU_ITEM_UNIVERSAL_IDENTIFIERS,
+  PDL_FRONT_COMPONENT_UNIVERSAL_IDENTIFIERS
+} from 'src/constants/universal-identifiers';
+
+export default defineCommandMenuItem({
+  universalIdentifier: PDL_COMMAND_MENU_ITEM_UNIVERSAL_IDENTIFIERS.enrichPeople,
+  availabilityObjectUniversalIdentifier: STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.person.universalIdentifier,
+  frontComponentUniversalIdentifier:
+  PDL_FRONT_COMPONENT_UNIVERSAL_IDENTIFIERS.enrichPeople,
+  label: 'Enrich people',
+  availabilityType: 'RECORD_SELECTION',
+});

package/src/constants/__tests__/select-option-constants.spec.ts

@@ -0,0 +1,142 @@
+import { describe, expect, it } from 'vitest';
+
+import { COMPANY_TYPE_OPTIONS } from 'src/constants/company-type-options';
+import { ENRICHMENT_STATUS_OPTIONS } from 'src/constants/enrichment-status-options';
+import { FUNDING_STAGE_OPTIONS } from 'src/constants/funding-stage-options';
+import { INDUSTRY_OPTIONS } from 'src/constants/industry-options';
+import { INFERRED_SALARY_OPTIONS } from 'src/constants/inferred-salary-options';
+import { JOB_ROLE_OPTIONS } from 'src/constants/job-role-options';
+import { JOB_TITLE_CLASS_OPTIONS } from 'src/constants/job-title-class-options';
+import { JOB_TITLE_SUB_ROLE_OPTIONS } from 'src/constants/job-title-sub-role-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 { SENIORITY_OPTIONS } from 'src/constants/seniority-options';
+import { SEX_OPTIONS } from 'src/constants/sex-options';
+import { SIZE_OPTIONS } from 'src/constants/size-options';
+import {
+  APPLICATION_UNIVERSAL_IDENTIFIER,
+  DEFAULT_ROLE_UNIVERSAL_IDENTIFIER,
+  PDL_FIELD_UNIVERSAL_IDENTIFIERS,
+  PDL_LOGIC_FUNCTION_CONSTANTS,
+  PDL_SELECT_OPTION_UNIVERSAL_IDENTIFIERS,
+  PDL_VIEW_UNIVERSAL_IDENTIFIERS
+} from 'src/constants/universal-identifiers';
+import { type SelectOptionMeta } from 'src/types/select-option-meta';
+import { normalizeEnumValue } from 'src/utils/normalize-enum-value';
+
+import companyEnrichmentStatusField from 'src/fields/company/pdl-enrichment-status.field';
+import companyFundingStagesField from 'src/fields/company/pdl-funding-stages.field';
+import companyIndustryField from 'src/fields/company/pdl-industry.field';
+import companyLatestFundingStageField from 'src/fields/company/pdl-latest-funding-stage.field';
+import companyLocationContinentField from 'src/fields/company/pdl-location-continent.field';
+import companyLocationMetroField from 'src/fields/company/pdl-location-metro.field';
+import companyMicExchangeField from 'src/fields/company/pdl-mic-exchange.field';
+import companySizeRangeField from 'src/fields/company/pdl-size-range.field';
+import companyTypeField from 'src/fields/company/pdl-company-type.field';
+import personEnrichmentStatusField from 'src/fields/person/pdl-enrichment-status.field';
+import personIndustryField from 'src/fields/person/pdl-industry.field';
+import personInferredSalaryField from 'src/fields/person/pdl-inferred-salary.field';
+import personJobRoleField from 'src/fields/person/pdl-job-role.field';
+import personJobTitleClassField from 'src/fields/person/pdl-job-title-class.field';
+import personJobTitleSubRoleField from 'src/fields/person/pdl-job-title-sub-role.field';
+import personLocationMetroField from 'src/fields/person/pdl-location-metro.field';
+import personSeniorityField from 'src/fields/person/pdl-seniority.field';
+import personSexField from 'src/fields/person/pdl-sex.field';
+
+type FieldOption = { id?: string; value: string };
+
+const fieldOptions = (field: unknown): FieldOption[] =>
+  (field as { config?: { options?: FieldOption[] } }).config?.options ?? [];
+
+const selectFieldCases: {
+  name: string;
+  field: unknown;
+  options: readonly SelectOptionMeta[];
+}[] = [
+  { name: 'person.pdlSeniority', field: personSeniorityField, options: SENIORITY_OPTIONS },
+  { name: 'person.pdlJobRole', field: personJobRoleField, options: JOB_ROLE_OPTIONS },
+  { name: 'person.pdlJobTitleClass', field: personJobTitleClassField, options: JOB_TITLE_CLASS_OPTIONS },
+  { name: 'person.pdlJobTitleSubRole', field: personJobTitleSubRoleField, options: JOB_TITLE_SUB_ROLE_OPTIONS },
+  { name: 'person.pdlSex', field: personSexField, options: SEX_OPTIONS },
+  { name: 'person.pdlInferredSalary', field: personInferredSalaryField, options: INFERRED_SALARY_OPTIONS },
+  { name: 'person.pdlIndustry', field: personIndustryField, options: INDUSTRY_OPTIONS },
+  { name: 'person.pdlLocationMetro', field: personLocationMetroField, options: METRO_OPTIONS },
+  { name: 'person.pdlEnrichmentStatus', field: personEnrichmentStatusField, options: ENRICHMENT_STATUS_OPTIONS },
+  { name: 'company.pdlCompanyType', field: companyTypeField, options: COMPANY_TYPE_OPTIONS },
+  { name: 'company.pdlLocationContinent', field: companyLocationContinentField, options: LOCATION_CONTINENT_OPTIONS },
+  { name: 'company.pdlMicExchange', field: companyMicExchangeField, options: MIC_EXCHANGE_OPTIONS },
+  { name: 'company.pdlIndustry', field: companyIndustryField, options: INDUSTRY_OPTIONS },
+  { name: 'company.pdlLocationMetro', field: companyLocationMetroField, options: METRO_OPTIONS },
+  { name: 'company.pdlSizeRange', field: companySizeRangeField, options: SIZE_OPTIONS },
+  { name: 'company.pdlLatestFundingStage', field: companyLatestFundingStageField, options: FUNDING_STAGE_OPTIONS },
+  { name: 'company.pdlFundingStages', field: companyFundingStagesField, options: FUNDING_STAGE_OPTIONS },
+  { name: 'company.pdlEnrichmentStatus', field: companyEnrichmentStatusField, options: ENRICHMENT_STATUS_OPTIONS },
+];
+
+describe.each(selectFieldCases)('$name options', ({ field, options }) => {
+  it('resolves a universalIdentifier for every option', () => {
+    expect(fieldOptions(field).every((option) => Boolean(option.id))).toBe(true);
+  });
+
+  it('exposes exactly the values from its source constant', () => {
+    expect(fieldOptions(field).map((option) => option.value)).toEqual(
+      options.map((option) => option.value),
+    );
+  });
+
+  it('uses option values that are normalizeEnumValue fixed points', () => {
+    for (const option of fieldOptions(field)) {
+      expect(normalizeEnumValue(option.value)).toBe(option.value);
+    }
+  });
+
+  it('has option ids that are unique within the field', () => {
+    const ids = fieldOptions(field).map((option) => option.id);
+    expect(new Set(ids).size).toBe(ids.length);
+  });
+});
+
+describe('select fields collectively', () => {
+  it('never reuses an option id across two different fields', () => {
+    const everyOptionId = selectFieldCases.flatMap(({ field }) =>
+      fieldOptions(field).map((option) => option.id),
+    );
+
+    expect(new Set(everyOptionId).size).toBe(everyOptionId.length);
+  });
+});
+
+const UUID_V4_REGEX =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+
+const collectUuids = (value: unknown): string[] => {
+  if (typeof value === 'string') {
+    return [value];
+  }
+  if (value !== null && typeof value === 'object') {
+    return Object.values(value).flatMap(collectUuids);
+  }
+  return [];
+};
+
+describe('universal-identifier registry', () => {
+  const registryUuids = collectUuids([
+    APPLICATION_UNIVERSAL_IDENTIFIER,
+    DEFAULT_ROLE_UNIVERSAL_IDENTIFIER,
+    PDL_LOGIC_FUNCTION_CONSTANTS,
+    PDL_FIELD_UNIVERSAL_IDENTIFIERS,
+    PDL_VIEW_UNIVERSAL_IDENTIFIERS,
+    PDL_SELECT_OPTION_UNIVERSAL_IDENTIFIERS,
+  ]);
+
+  it('contains only valid v4 UUIDs', () => {
+    expect(registryUuids.filter((uuid) => !UUID_V4_REGEX.test(uuid))).toEqual(
+      [],
+    );
+  });
+
+  it('contains no duplicate UUIDs across the whole registry', () => {
+    expect(new Set(registryUuids).size).toBe(registryUuids.length);
+  });
+});

package/src/constants/billing-margin-multiplier.ts

@@ -0,0 +1 @@
+export const BILLING_MARGIN_MULTIPLIER = 1.2;

package/src/constants/company-match-cost-dollars.ts

@@ -0,0 +1 @@
+export const COMPANY_MATCH_COST_DOLLARS = 0.1;

package/src/constants/company-type-options.ts

@@ -0,0 +1,46 @@
+import { type SelectOptionMeta } from 'src/types/select-option-meta';
+
+export const COMPANY_TYPE_OPTIONS: readonly SelectOptionMeta[] = [
+  {
+    key: 'public',
+    value: 'PUBLIC',
+    label: 'Public',
+    color: 'blue',
+    position: 0,
+  },
+  {
+    key: 'private',
+    value: 'PRIVATE',
+    label: 'Private',
+    color: 'red',
+    position: 1,
+  },
+  {
+    key: 'publicSubsidiary',
+    value: 'PUBLIC_SUBSIDIARY',
+    label: 'Public Subsidiary',
+    color: 'green',
+    position: 2,
+  },
+  {
+    key: 'educational',
+    value: 'EDUCATIONAL',
+    label: 'Educational',
+    color: 'orange',
+    position: 3,
+  },
+  {
+    key: 'government',
+    value: 'GOVERNMENT',
+    label: 'Government',
+    color: 'purple',
+    position: 4,
+  },
+  {
+    key: 'nonprofit',
+    value: 'NONPROFIT',
+    label: 'Nonprofit',
+    color: 'yellow',
+    position: 5,
+  },
+];

package/src/constants/enrichment-status-options.ts

@@ -0,0 +1,19 @@
+import { type SelectOptionMeta } from 'src/types/select-option-meta';
+
+export const ENRICHMENT_STATUS_OPTIONS: readonly SelectOptionMeta[] = [
+  {
+    key: 'matched',
+    value: 'MATCHED',
+    label: 'Matched',
+    color: 'green',
+    position: 0,
+  },
+  {
+    key: 'notFound',
+    value: 'NOT_FOUND',
+    label: 'No Match',
+    color: 'gray',
+    position: 1,
+  },
+  { key: 'error', value: 'ERROR', label: 'Error', color: 'red', position: 2 },
+];

package/src/constants/enrichment-workflow-seeds.ts

@@ -0,0 +1,27 @@
+import { PDL_LOGIC_FUNCTION_CONSTANTS } from 'src/constants/universal-identifiers';
+import { type EnrichmentWorkflowSeed } from 'src/types/enrichment-workflow-seed';
+
+const ENRICHMENT_ICON = 'IconSparkles';
+
+export const ENRICHMENT_WORKFLOW_SEEDS: EnrichmentWorkflowSeed[] = [
+  {
+    objectNameSingular: 'company',
+    workflowName: 'Enrich companies with People Data Labs',
+    triggerName: 'When companies are selected',
+    icon: ENRICHMENT_ICON,
+    stepName: 'Enrich Companies',
+    logicFunctionUniversalIdentifier:
+      PDL_LOGIC_FUNCTION_CONSTANTS.enrichCompanies.universalIdentifier,
+    logicFunctionInput: { records: '{{trigger.companies}}' },
+  },
+  {
+    objectNameSingular: 'person',
+    workflowName: 'Enrich people with People Data Labs',
+    triggerName: 'When people are selected',
+    icon: ENRICHMENT_ICON,
+    stepName: 'Enrich People',
+    logicFunctionUniversalIdentifier:
+      PDL_LOGIC_FUNCTION_CONSTANTS.enrichPeople.universalIdentifier,
+    logicFunctionInput: { records: '{{trigger.people}}' },
+  },
+];