The open alternative to Salesforce, designed for AI.
TypeScript crmcrm-systemcustomergood-first-issuegraphqlhacktoberfestjavascriptmarketingmonoreponestjsopen-sourcepostgresqlreactreactjssalestypescriptweb
import { ToolCategory } from 'twenty-shared/ai';
import { type FieldMetadataType } from 'twenty-shared/types';
import { isDefined } from 'twenty-shared/utils';
import { z } from 'zod';
import { METADATA_TOOL_EXCLUDED_FIELD_NAMES } from 'src/engine/core-modules/tool-provider/constants/metadata-tool-excluded-field-names.constant';
import { DefineTool } from 'src/engine/core-modules/tool-provider/decorators/define-tool.decorator';
import { BaseTool } from 'src/engine/core-modules/tool-provider/interfaces/base-tool.interface';
import { type ToolExecuteArgs } from 'src/engine/core-modules/tool-provider/types/tool-execute-args.type';
import { compactMetadataOutput } from 'src/engine/core-modules/tool-provider/utils/compact-metadata-output.util';
import { type ToolOutput } from 'src/engine/core-modules/tool/types/tool-output.type';
import { WorkspaceManyOrAllFlatEntityMapsCacheService } from 'src/engine/metadata-modules/flat-entity/services/workspace-many-or-all-flat-entity-maps-cache.service';
import { fromFlatObjectMetadataToObjectMetadataDto } from 'src/engine/metadata-modules/flat-object-metadata/utils/from-flat-object-metadata-to-object-metadata-dto.util';
import { OBJECT_METADATA_READ_ACCESS_POLICY } from 'src/engine/metadata-modules/object-metadata/constants/object-metadata-read-access-policy.constant';
import { ObjectMetadataService } from 'src/engine/metadata-modules/object-metadata/object-metadata.service';
type InlinedObjectFieldSummary = {
id: string;
name: string;
type: FieldMetadataType;
label: string;
};
const OBJECT_STRIP_WHEN_NULLISH = [
'overrides',
'color',
'duplicateCriteria',
'shortcut',
'imageIdentifierFieldMetadataId',
'description',
'icon',
];
const getObjectMetadataInputSchema = z.object({
id: z.uuid().optional().describe('Object ID. Returns one object if set.'),
objectName: z
.string()
.optional()
.describe(
'Filter by object name, singular or plural (e.g. "opportunity" or "opportunities"). Lets you locate an object by name in one call without scanning the full list.',
),
includeFields: z
.boolean()
.default(false)
.describe(
'When true, each returned object includes its fields as a compact array of {id, name, type, label}. Use this to fetch an object and all the field ids you need in a single call (e.g. before building a dashboard) instead of a separate get_field_metadata call.',
),
includeFullSystemObjects: z
.boolean()
.default(false)
.describe(
"Keep false (default) for listing or locating objects — system objects then return as compact {id, nameSingular, namePlural}, which is enough to find an object and read its id. Only set true when you specifically need a system object's full configuration (e.g. building a relation to workspaceMember).",
),
limit: z
.number()
.int()
.min(1)
.max(100)
.default(100)
.describe('Max objects to return.'),
});
@DefineTool({
name: 'get_object_metadata',
category: ToolCategory.METADATA,
accessPolicy: OBJECT_METADATA_READ_ACCESS_POLICY,
icon: 'IconSettings',
description:
"List object metadata, returned as { objects: [...] } in the result. Filter to a single object by id or objectName (singular or plural). Set includeFields to also return each object's fields ({id, name, type, label}) — enough to build a dashboard or view without a separate get_field_metadata call. System objects are otherwise returned as compact {id, nameSingular, namePlural}. Keep includeFullSystemObjects at its default (false); only set it true when you specifically need a system object's full configuration.",
})
export class GetObjectMetadataTool extends BaseTool<
typeof getObjectMetadataInputSchema
> {
readonly inputSchema = getObjectMetadataInputSchema;
constructor(
private readonly objectMetadataService: ObjectMetadataService,
private readonly flatEntityMapsCacheService: WorkspaceManyOrAllFlatEntityMapsCacheService,
) {
super();
}
async execute({
input,
context: { workspaceId },
}: ToolExecuteArgs<
typeof getObjectMetadataInputSchema
>): Promise<ToolOutput> {
const flatObjectMetadatas =
await this.objectMetadataService.findManyWithinWorkspace(workspaceId, {
...(input.id
? { where: { id: input.id } }
: input.objectName
? {
where: [
{ nameSingular: input.objectName },
{ namePlural: input.objectName },
],
}
: {}),
take: input.limit ?? 100,
});
const fieldsByObjectId = input.includeFields
? await this.buildFieldsByObjectId(workspaceId)
: undefined;
const objects = flatObjectMetadatas.map((flatObjectMetadata) => {
const dto = fromFlatObjectMetadataToObjectMetadataDto(flatObjectMetadata);
const fields = fieldsByObjectId?.get(dto.id) ?? [];
if (dto.isSystem && !input.includeFullSystemObjects) {
return {
id: dto.id,
nameSingular: dto.nameSingular,
namePlural: dto.namePlural,
...(input.includeFields ? { fields } : {}),
};
}
return compactMetadataOutput(
{
...dto,
...(input.includeFields ? { fields } : {}),
},
{ stripWhenNullish: OBJECT_STRIP_WHEN_NULLISH },
);
});
return {
success: true,
message: `Found ${objects.length} object(s).`,
result: { objects },
};
}
private async buildFieldsByObjectId(
workspaceId: string,
): Promise<Map<string, InlinedObjectFieldSummary[]>> {
const { flatFieldMetadataMaps } =
await this.flatEntityMapsCacheService.getOrRecomputeManyOrAllFlatEntityMaps(
{
workspaceId,
flatMapsKeys: ['flatFieldMetadataMaps'],
},
);
const fieldsByObjectId = new Map<string, InlinedObjectFieldSummary[]>();
for (const fieldMetadata of Object.values(
flatFieldMetadataMaps.byUniversalIdentifier,
)) {
if (
!isDefined(fieldMetadata) ||
METADATA_TOOL_EXCLUDED_FIELD_NAMES.has(fieldMetadata.name)
) {
continue;
}
const existing =
fieldsByObjectId.get(fieldMetadata.objectMetadataId) ?? [];
existing.push({
id: fieldMetadata.id,
name: fieldMetadata.name,
type: fieldMetadata.type,
label: fieldMetadata.label ?? fieldMetadata.name,
});
fieldsByObjectId.set(fieldMetadata.objectMetadataId, existing);
}
return fieldsByObjectId;
}
}