@twentyhq/people-data-labs 1.0.0

package/src/logic-functions/enrich-person.function.ts

@@ -0,0 +1,73 @@
+import { defineLogicFunction } from 'twenty-sdk/define';
+
+import { UPDATE_FIELDS_OPTION_VALUES } from 'src/constants/update-fields-option-values';
+import { PDL_LOGIC_FUNCTION_CONSTANTS } from 'src/constants/universal-identifiers';
+import { enrichPersonCore } from 'src/logic-functions/handlers/enrich-person';
+import { type SingleEnrichInput } from 'src/types/single-enrich-input';
+
+const handler = (input: SingleEnrichInput) => enrichPersonCore({ input });
+
+export default defineLogicFunction({
+  universalIdentifier: PDL_LOGIC_FUNCTION_CONSTANTS.enrichPerson.universalIdentifier,
+  name: 'enrich-person',
+  description:
+    'Enrich a single Person record with People Data Labs data (job, location, social profiles, etc.) given its record id.',
+  timeoutSeconds: 60,
+  handler,
+  workflowActionTriggerSettings: {
+    label: 'Enrich Person',
+    icon: 'IconSparkles',
+    inputSchema: [
+      {
+        type: 'object',
+        properties: {
+          recordId: {
+            type: 'string',
+            label: 'Record',
+          },
+          updateFields: {
+            type: 'string',
+            label: 'Update fields',
+            enum: [...UPDATE_FIELDS_OPTION_VALUES],
+          },
+        },
+      },
+    ],
+    outputSchema: [
+      {
+        type: 'object',
+        properties: {
+          success: { type: 'boolean', label: 'Success' },
+          recordId: { type: 'string', label: 'Record Id' },
+          status: { type: 'string', label: 'Status' },
+          updatedFields: {
+            type: 'array',
+            items: { type: 'string' },
+            label: 'Updated Fields',
+          },
+          data: { type: 'object', label: 'Data' },
+          message: { type: 'string', label: 'Message' },
+        },
+      },
+    ],
+  },
+  toolTriggerSettings: {
+    inputSchema: {
+      type: 'object',
+      properties: {
+        recordId: {
+          type: 'string',
+          description: 'The id of the Person record to enrich.',
+        },
+        updateFields: {
+          type: 'string',
+          enum: [...UPDATE_FIELDS_OPTION_VALUES],
+          description:
+            'Whether to write the enriched data back to the record. "Yes and overwrite" replaces existing values; "Yes and don\'t overwrite" only fills empty fields; "No" returns the enriched data without modifying the record.',
+        },
+      },
+      required: ['recordId'],
+      additionalProperties: false,
+    },
+  },
+});

package/src/logic-functions/errors/__tests__/pdl-config-error.spec.ts

@@ -0,0 +1,16 @@
+import { describe, expect, it } from 'vitest';
+
+import { PdlConfigError } from 'src/logic-functions/errors/pdl-config-error';
+import { PdlError } from 'src/logic-functions/errors/pdl-error';
+
+describe('PdlConfigError', () => {
+  it('is a PdlError with a dedicated name, code, and the given message', () => {
+    const error = new PdlConfigError('missing key');
+
+    expect(error).toBeInstanceOf(Error);
+    expect(error).toBeInstanceOf(PdlError);
+    expect(error.name).toBe('PdlConfigError');
+    expect(error.code).toBe('CONFIGURATION');
+    expect(error.message).toBe('missing key');
+  });
+});

package/src/logic-functions/errors/__tests__/pdl-invalid-input-error.spec.ts

@@ -0,0 +1,16 @@
+import { describe, expect, it } from 'vitest';
+
+import { PdlError } from 'src/logic-functions/errors/pdl-error';
+import { PdlInvalidInputError } from 'src/logic-functions/errors/pdl-invalid-input-error';
+
+describe('PdlInvalidInputError', () => {
+  it('is a PdlError with a dedicated name, code, and the given message', () => {
+    const error = new PdlInvalidInputError('recordId is required');
+
+    expect(error).toBeInstanceOf(Error);
+    expect(error).toBeInstanceOf(PdlError);
+    expect(error.name).toBe('PdlInvalidInputError');
+    expect(error.code).toBe('INVALID_INPUT');
+    expect(error.message).toBe('recordId is required');
+  });
+});

package/src/logic-functions/errors/__tests__/pdl-operation-error.spec.ts

@@ -0,0 +1,16 @@
+import { describe, expect, it } from 'vitest';
+
+import { PdlError } from 'src/logic-functions/errors/pdl-error';
+import { PdlOperationError } from 'src/logic-functions/errors/pdl-operation-error';
+
+describe('PdlOperationError', () => {
+  it('is a PdlError with a dedicated name, code, and the given message', () => {
+    const error = new PdlOperationError('no id returned');
+
+    expect(error).toBeInstanceOf(Error);
+    expect(error).toBeInstanceOf(PdlError);
+    expect(error.name).toBe('PdlOperationError');
+    expect(error.code).toBe('OPERATION_FAILED');
+    expect(error.message).toBe('no id returned');
+  });
+});

package/src/logic-functions/errors/__tests__/pdl-record-not-found-error.spec.ts

@@ -0,0 +1,21 @@
+import { describe, expect, it } from 'vitest';
+
+import { PdlError } from 'src/logic-functions/errors/pdl-error';
+import { PdlRecordNotFoundError } from 'src/logic-functions/errors/pdl-record-not-found-error';
+
+describe('PdlRecordNotFoundError', () => {
+  it('exposes the object type and record id alongside a built message', () => {
+    const error = new PdlRecordNotFoundError({
+      objectNameSingular: 'Person',
+      recordId: 'p1',
+    });
+
+    expect(error).toBeInstanceOf(Error);
+    expect(error).toBeInstanceOf(PdlError);
+    expect(error.name).toBe('PdlRecordNotFoundError');
+    expect(error.code).toBe('RECORD_NOT_FOUND');
+    expect(error.objectNameSingular).toBe('Person');
+    expect(error.recordId).toBe('p1');
+    expect(error.message).toBe('Person p1 not found');
+  });
+});

package/src/logic-functions/errors/pdl-config-error.ts

@@ -0,0 +1,8 @@
+import { PdlError } from 'src/logic-functions/errors/pdl-error';
+import { PdlErrorCode } from 'src/logic-functions/errors/pdl-error-code';
+
+export class PdlConfigError extends PdlError {
+  constructor(message: string) {
+    super({ message, code: PdlErrorCode.CONFIGURATION });
+  }
+}

package/src/logic-functions/errors/pdl-error-code.ts

@@ -0,0 +1,8 @@
+export const PdlErrorCode = {
+  CONFIGURATION: 'CONFIGURATION',
+  INVALID_INPUT: 'INVALID_INPUT',
+  RECORD_NOT_FOUND: 'RECORD_NOT_FOUND',
+  OPERATION_FAILED: 'OPERATION_FAILED',
+} as const;
+
+export type PdlErrorCode = (typeof PdlErrorCode)[keyof typeof PdlErrorCode];

package/src/logic-functions/errors/pdl-error.ts

@@ -0,0 +1,12 @@
+import { type PdlErrorCode } from 'src/logic-functions/errors/pdl-error-code';
+
+export abstract class PdlError extends Error {
+  readonly code: PdlErrorCode;
+
+  constructor({ message, code }: { message: string; code: PdlErrorCode }) {
+    super(message);
+    Object.setPrototypeOf(this, new.target.prototype);
+    this.name = new.target.name;
+    this.code = code;
+  }
+}

package/src/logic-functions/errors/pdl-invalid-input-error.ts

@@ -0,0 +1,8 @@
+import { PdlError } from 'src/logic-functions/errors/pdl-error';
+import { PdlErrorCode } from 'src/logic-functions/errors/pdl-error-code';
+
+export class PdlInvalidInputError extends PdlError {
+  constructor(message: string) {
+    super({ message, code: PdlErrorCode.INVALID_INPUT });
+  }
+}

package/src/logic-functions/errors/pdl-operation-error.ts

@@ -0,0 +1,8 @@
+import { PdlError } from 'src/logic-functions/errors/pdl-error';
+import { PdlErrorCode } from 'src/logic-functions/errors/pdl-error-code';
+
+export class PdlOperationError extends PdlError {
+  constructor(message: string) {
+    super({ message, code: PdlErrorCode.OPERATION_FAILED });
+  }
+}

package/src/logic-functions/errors/pdl-record-not-found-error.ts

@@ -0,0 +1,22 @@
+import { PdlError } from 'src/logic-functions/errors/pdl-error';
+import { PdlErrorCode } from 'src/logic-functions/errors/pdl-error-code';
+
+export class PdlRecordNotFoundError extends PdlError {
+  readonly objectNameSingular: string;
+  readonly recordId: string;
+
+  constructor({
+    objectNameSingular,
+    recordId,
+  }: {
+    objectNameSingular: string;
+    recordId: string;
+  }) {
+    super({
+      message: `${objectNameSingular} ${recordId} not found`,
+      code: PdlErrorCode.RECORD_NOT_FOUND,
+    });
+    this.objectNameSingular = objectNameSingular;
+    this.recordId = recordId;
+  }
+}

package/src/logic-functions/handlers/__tests__/enrich-companies.spec.ts

@@ -0,0 +1,159 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { type CoreApiClient } from 'twenty-client-sdk/core';
+
+import { COMPANY_NODE_MOCK } from 'src/logic-functions/__mocks__/company-node.mock';
+import { createCoreApiClientMock } from 'src/logic-functions/__mocks__/create-core-api-client-mock';
+import { enrichCompaniesCore } from 'src/logic-functions/handlers/enrich-companies';
+import { enrichCompanies } from 'src/logic-functions/utils/enrich-companies';
+import { type CompanyNode } from 'src/types/company-node';
+
+vi.mock('src/logic-functions/utils/enrich-companies', () => ({
+  enrichCompanies: vi.fn(),
+}));
+
+const enrichCompaniesMock = vi.mocked(enrichCompanies);
+
+type Captured = {
+  updateCompany?: Record<string, unknown>;
+  updateCompanies?: { filter: unknown; data: Record<string, unknown> };
+};
+
+type MutationRequest = {
+  updateCompany?: { __args: { id: string; data: Record<string, unknown> } };
+  updateCompanies?: { __args: { filter: unknown; data: Record<string, unknown> } };
+};
+
+const captureMutation = (captured: Captured) => (request: unknown) => {
+  const mutation = request as MutationRequest;
+  if (mutation.updateCompany) {
+    captured.updateCompany = mutation.updateCompany.__args.data;
+  }
+  if (mutation.updateCompanies) {
+    captured.updateCompanies = {
+      filter: mutation.updateCompanies.__args.filter,
+      data: mutation.updateCompanies.__args.data,
+    };
+  }
+};
+
+const buildClient = (companies: CompanyNode[], captured: Captured): CoreApiClient =>
+  createCoreApiClientMock({
+    queryResult: { companies: { edges: companies.map((node) => ({ node })) } },
+    onMutation: captureMutation(captured),
+  });
+
+const runOne = (client: CoreApiClient, recordId = 'c1') =>
+  enrichCompaniesCore({ input: { records: [{ id: recordId }] }, client });
+
+beforeEach(() => {
+  enrichCompaniesMock.mockReset();
+});
+
+describe('enrichCompaniesCore', () => {
+  it('fills empty standard fields and writes pdl metadata via updateCompany on a match', async () => {
+    enrichCompaniesMock.mockResolvedValue([
+      {
+        outcome: 'matched',
+        httpStatus: 200,
+        data: {
+          id: 'pdlc',
+          display_name: 'Acme Corp',
+          website: 'newsite.com',
+          industry: 'accounting',
+        },
+      },
+    ]);
+    const captured: Captured = {};
+    const client = buildClient([COMPANY_NODE_MOCK], captured);
+
+    const result = await runOne(client);
+
+    expect(enrichCompaniesMock).toHaveBeenCalledTimes(1);
+    expect(result.matched).toBe(1);
+    expect(captured.updateCompany?.name).toBe('Acme Corp');
+    expect(captured.updateCompany?.pdlIndustry).toBe('ACCOUNTING');
+    expect(captured.updateCompany?.pdlEnrichmentStatus).toBe('MATCHED');
+    expect(typeof captured.updateCompany?.pdlLastEnrichedAt).toBe('string');
+    expect('domainName' in (captured.updateCompany ?? {})).toBe(false);
+    expect('pdlLikelihood' in (captured.updateCompany ?? {})).toBe(false);
+  });
+
+  it('records NOT_FOUND and writes the status via a batched updateCompanies', async () => {
+    enrichCompaniesMock.mockResolvedValue([{ outcome: 'not_found', httpStatus: 404 }]);
+    const captured: Captured = {};
+    const client = buildClient([COMPANY_NODE_MOCK], captured);
+
+    const result = await runOne(client);
+
+    expect(result.notFound).toBe(1);
+    expect(captured.updateCompany).toBeUndefined();
+    expect(Object.keys(captured.updateCompanies?.data ?? {}).sort()).toEqual([
+      'pdlEnrichmentStatus',
+      'pdlLastEnrichedAt',
+    ]);
+    expect(captured.updateCompanies?.filter).toEqual({ id: { in: ['c1'] } });
+  });
+
+  it('records ERROR and reports failure on a PDL error', async () => {
+    enrichCompaniesMock.mockResolvedValue([
+      { outcome: 'error', httpStatus: 500, message: 'boom' },
+    ]);
+    const captured: Captured = {};
+    const client = buildClient([COMPANY_NODE_MOCK], captured);
+
+    const result = await runOne(client);
+
+    expect(result.errored).toBe(1);
+    expect(result.success).toBe(false);
+    expect(result.results[0].error).toBe('boom');
+    expect(captured.updateCompanies?.data).toEqual({
+      pdlEnrichmentStatus: 'ERROR',
+      pdlLastEnrichedAt: expect.any(String),
+    });
+  });
+
+  it('skips when there is no usable identifier', async () => {
+    const captured: Captured = {};
+    const client = buildClient(
+      [{ ...COMPANY_NODE_MOCK, domainName: null, name: '' }],
+      captured,
+    );
+
+    const result = await runOne(client);
+
+    expect(result.skipped).toBe(1);
+    expect(enrichCompaniesMock).not.toHaveBeenCalled();
+  });
+
+  it('marks a missing record as ERROR', async () => {
+    const captured: Captured = {};
+    const client = buildClient([], captured);
+
+    const result = await runOne(client, 'missing');
+
+    expect(result.errored).toBe(1);
+    expect(result.results[0].error).toBe('Company missing not found');
+    expect(enrichCompaniesMock).not.toHaveBeenCalled();
+  });
+
+  it('batches the PDL request and the not-found status write across records', async () => {
+    enrichCompaniesMock.mockResolvedValue([
+      { outcome: 'not_found', httpStatus: 404 },
+      { outcome: 'not_found', httpStatus: 404 },
+    ]);
+    const captured: Captured = {};
+    const client = buildClient(
+      [COMPANY_NODE_MOCK, { ...COMPANY_NODE_MOCK, id: 'c2' }],
+      captured,
+    );
+
+    const result = await enrichCompaniesCore({
+      input: { records: [{ id: 'c1' }, { id: 'c2' }] },
+      client,
+    });
+
+    expect(enrichCompaniesMock).toHaveBeenCalledTimes(1);
+    expect(captured.updateCompanies?.filter).toEqual({ id: { in: ['c1', 'c2'] } });
+    expect(result.notFound).toBe(2);
+  });
+});

package/src/logic-functions/handlers/__tests__/enrich-company.spec.ts

@@ -0,0 +1,147 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { type CoreApiClient } from 'twenty-client-sdk/core';
+
+import { COMPANY_NODE_MOCK } from 'src/logic-functions/__mocks__/company-node.mock';
+import { createCoreApiClientMock } from 'src/logic-functions/__mocks__/create-core-api-client-mock';
+import { enrichCompanyCore } from 'src/logic-functions/handlers/enrich-company';
+import { enrichCompany } from 'src/logic-functions/utils/enrich-company';
+import { type CompanyNode } from 'src/types/company-node';
+
+vi.mock('src/logic-functions/utils/enrich-company', () => ({
+  enrichCompany: vi.fn(),
+}));
+
+const enrichCompanyMock = vi.mocked(enrichCompany);
+
+type Captured = {
+  updateCompany?: Record<string, unknown>;
+  updateCompanies?: { filter: unknown; data: Record<string, unknown> };
+};
+
+type MutationRequest = {
+  updateCompany?: { __args: { id: string; data: Record<string, unknown> } };
+  updateCompanies?: { __args: { filter: unknown; data: Record<string, unknown> } };
+};
+
+const captureMutation = (captured: Captured) => (request: unknown) => {
+  const mutation = request as MutationRequest;
+  if (mutation.updateCompany) {
+    captured.updateCompany = mutation.updateCompany.__args.data;
+  }
+  if (mutation.updateCompanies) {
+    captured.updateCompanies = {
+      filter: mutation.updateCompanies.__args.filter,
+      data: mutation.updateCompanies.__args.data,
+    };
+  }
+};
+
+const buildClient = (companies: CompanyNode[], captured: Captured): CoreApiClient =>
+  createCoreApiClientMock({
+    queryResult: { companies: { edges: companies.map((node) => ({ node })) } },
+    onMutation: captureMutation(captured),
+  });
+
+const runOne = (client: CoreApiClient, recordId = 'c1') =>
+  enrichCompanyCore({ input: { recordId }, client });
+
+beforeEach(() => {
+  enrichCompanyMock.mockReset();
+});
+
+describe('enrichCompanyCore', () => {
+  it('fills empty standard fields and writes pdl metadata via updateCompany on a match', async () => {
+    enrichCompanyMock.mockResolvedValue([
+      {
+        outcome: 'matched',
+        httpStatus: 200,
+        data: {
+          id: 'pdlc',
+          display_name: 'Acme Corp',
+          website: 'newsite.com',
+          industry: 'accounting',
+        },
+      },
+    ]);
+    const captured: Captured = {};
+    const client = buildClient([COMPANY_NODE_MOCK], captured);
+
+    const result = await runOne(client);
+
+    expect(enrichCompanyMock).toHaveBeenCalledTimes(1);
+    expect(result.status).toBe('MATCHED');
+    expect(result.success).toBe(true);
+    expect(result.recordId).toBe('c1');
+    expect(result.updatedFields).toContain('name');
+    expect(captured.updateCompany?.name).toBe('Acme Corp');
+    expect(captured.updateCompany?.pdlIndustry).toBe('ACCOUNTING');
+    expect(captured.updateCompany?.pdlEnrichmentStatus).toBe('MATCHED');
+  });
+
+  it('records NOT_FOUND and writes the status via updateCompanies', async () => {
+    enrichCompanyMock.mockResolvedValue([{ outcome: 'not_found', httpStatus: 404 }]);
+    const captured: Captured = {};
+    const client = buildClient([COMPANY_NODE_MOCK], captured);
+
+    const result = await runOne(client);
+
+    expect(result.status).toBe('NOT_FOUND');
+    expect(result.success).toBe(true);
+    expect(captured.updateCompany).toBeUndefined();
+    expect(captured.updateCompanies?.data.pdlEnrichmentStatus).toBe('NOT_FOUND');
+    expect(captured.updateCompanies?.filter).toEqual({ id: { in: ['c1'] } });
+  });
+
+  it('records ERROR and reports failure on a PDL error', async () => {
+    enrichCompanyMock.mockResolvedValue([
+      { outcome: 'error', httpStatus: 500, message: 'boom' },
+    ]);
+    const captured: Captured = {};
+    const client = buildClient([COMPANY_NODE_MOCK], captured);
+
+    const result = await runOne(client);
+
+    expect(result.status).toBe('ERROR');
+    expect(result.success).toBe(false);
+    expect(result.error).toBe('boom');
+    expect(captured.updateCompanies?.data).toEqual({
+      pdlEnrichmentStatus: 'ERROR',
+      pdlLastEnrichedAt: expect.any(String),
+    });
+  });
+
+  it('skips when there is no usable identifier', async () => {
+    const captured: Captured = {};
+    const client = buildClient(
+      [{ ...COMPANY_NODE_MOCK, domainName: null, name: '' }],
+      captured,
+    );
+
+    const result = await runOne(client);
+
+    expect(result.status).toBe('SKIPPED');
+    expect(enrichCompanyMock).not.toHaveBeenCalled();
+  });
+
+  it('marks a missing record as ERROR', async () => {
+    const captured: Captured = {};
+    const client = buildClient([], captured);
+
+    const result = await runOne(client, 'missing');
+
+    expect(result.status).toBe('ERROR');
+    expect(result.error).toBe('Company missing not found');
+    expect(enrichCompanyMock).not.toHaveBeenCalled();
+  });
+
+  it('returns an ERROR without touching PDL when no record id is provided', async () => {
+    const captured: Captured = {};
+    const client = buildClient([COMPANY_NODE_MOCK], captured);
+
+    const result = await enrichCompanyCore({ input: {}, client });
+
+    expect(result.status).toBe('ERROR');
+    expect(result.error).toBe('No record id was provided to enrich.');
+    expect(enrichCompanyMock).not.toHaveBeenCalled();
+  });
+});