The open alternative to Salesforce, designed for AI.
TypeScript crmcrm-systemcustomergood-first-issuegraphqlhacktoberfestjavascriptmarketingmonoreponestjsopen-sourcepostgresqlreactreactjssalestypescriptweb
Build the find tool orderBy schema from the object's fields (#27010)
Félix Malfaitc441cac01a2a
diff --git a/packages/twenty-server/src/engine/core-modules/record-crud/zod-schemas/__tests__/find-tool.zod-schema.spec.ts b/packages/twenty-server/src/engine/core-modules/record-crud/zod-schemas/__tests__/find-tool.zod-schema.spec.tsnew file mode 100644index 00000000000..944ac3eec3d--- /dev/null+++ b/packages/twenty-server/src/engine/core-modules/record-crud/zod-schemas/__tests__/find-tool.zod-schema.spec.ts@@ -0,0 +1,125 @@+import { FieldMetadataType, RelationType } from 'twenty-shared/types';++import { type ObjectMetadataForToolSchema } from 'src/engine/core-modules/record-crud/types/object-metadata-for-tool-schema.type';+import { toToolJsonSchema } from 'src/engine/core-modules/record-crud/utils/to-tool-json-schema.util';+import { generateFindToolInputSchema } from 'src/engine/core-modules/record-crud/zod-schemas/find-tool.zod-schema';++const buildCompanyLikeObjectMetadata = (): ObjectMetadataForToolSchema => {+ return {+ fields: [+ {+ id: 'field-id-name',+ name: 'name',+ type: FieldMetadataType.TEXT,+ isSystem: false,+ },+ {+ id: 'field-id-address',+ name: 'address',+ type: FieldMetadataType.ADDRESS,+ isSystem: false,+ },+ {+ id: 'field-id-account-owner',+ name: 'accountOwner',+ type: FieldMetadataType.RELATION,+ isSystem: false,+ settings: { relationType: RelationType.MANY_TO_ONE },+ },+ {+ id: 'field-id-created-at',+ name: 'createdAt',+ type: FieldMetadataType.DATE_TIME,+ isSystem: true,+ },+ {+ id: 'field-id-deleted-at',+ name: 'deletedAt',+ type: FieldMetadataType.DATE_TIME,+ isSystem: true,+ },+ {+ id: 'field-id-people',+ name: 'people',+ type: FieldMetadataType.RELATION,+ isSystem: false,+ settings: { relationType: RelationType.ONE_TO_MANY },+ },+ ],+ } as unknown as ObjectMetadataForToolSchema;+};++const parseOrderBy = (orderBy: unknown, restrictedFields = {}) =>+ generateFindToolInputSchema(+ buildCompanyLikeObjectMetadata(),+ restrictedFields,+ ).safeParse({ select: ['*'], orderBy });++describe('generateFindToolInputSchema orderBy', () => {+ it.each([+ [[{ name: 'AscNullsFirst' }]],+ [[{ address: { addressCity: 'DescNullsLast' } }]],+ [[{ accountOwnerId: 'AscNullsLast' }]],+ [[{ createdAt: 'DescNullsLast' }]],+ [+ [+ { name: 'DescNullsLast' },+ { address: { addressCountry: 'AscNullsFirst' } },+ ],+ ],+ ])('accepts %j', (orderBy) => {+ expect(parseOrderBy(orderBy).success).toBe(true);+ });++ it.each([+ [[{ name: { firstName: 'AscNullsFirst' } }]],+ [[{ address: 'AscNullsFirst' }]],+ [[{ address: { unknownSubField: 'AscNullsFirst' } }]],+ [[{ people: 'AscNullsFirst' }]],+ [[{ unknownField: 'AscNullsFirst' }]],+ [[{ deletedAt: 'AscNullsFirst' }]],+ [[{ name: 'AscNullsFirst', address: { addressCity: 'AscNullsFirst' } }]],+ [[{ 'name.firstName': 'AscNullsFirst' }]],+ ])('rejects %j', (orderBy) => {+ expect(parseOrderBy(orderBy).success).toBe(false);+ });++ it('does not offer sorting on unreadable fields', () => {+ expect(+ parseOrderBy([{ name: 'AscNullsFirst' }], {+ 'field-id-name': { canRead: false },+ }).success,+ ).toBe(false);+ });++ it('advertises a direction for scalar fields and sub-fields for composite fields', () => {+ type JsonSchemaNode = {+ $ref?: string;+ enum?: string[];+ properties?: Record<string, JsonSchemaNode>;+ items?: JsonSchemaNode;+ };++ const jsonSchema = toToolJsonSchema(+ generateFindToolInputSchema(buildCompanyLikeObjectMetadata()),+ ) as JsonSchemaNode & { $defs: Record<string, JsonSchemaNode> };++ const resolve = (node: JsonSchemaNode | undefined) =>+ node?.$ref ? jsonSchema.$defs[node.$ref.replace('#/$defs/', '')] : node;++ const orderByItemProperties =+ jsonSchema.properties?.orderBy.items?.properties ?? {};++ expect(resolve(orderByItemProperties.name)?.enum).toContain(+ 'AscNullsFirst',+ );+ expect(resolve(orderByItemProperties.name)?.properties).toBeUndefined();+ expect(+ Object.keys(resolve(orderByItemProperties.address)?.properties ?? {}),+ ).toEqual(expect.arrayContaining(['addressCity', 'addressCountry']));+ expect(resolve(orderByItemProperties.accountOwnerId)?.enum).toContain(+ 'DescNullsLast',+ );+ expect(orderByItemProperties.people).toBeUndefined();+ });+});diff --git a/packages/twenty-server/src/engine/core-modules/record-crud/zod-schemas/find-tool.zod-schema.ts b/packages/twenty-server/src/engine/core-modules/record-crud/zod-schemas/find-tool.zod-schema.tsindex 7b23f671ce8..b85e737cfe3 100644--- a/packages/twenty-server/src/engine/core-modules/record-crud/zod-schemas/find-tool.zod-schema.ts+++ b/packages/twenty-server/src/engine/core-modules/record-crud/zod-schemas/find-tool.zod-schema.ts@@ -2,7 +2,7 @@ import { type RestrictedFieldsPermissions } from 'twenty-shared/types';import { z } from 'zod';import { type ObjectMetadataForToolSchema } from 'src/engine/core-modules/record-crud/types/object-metadata-for-tool-schema.type';-import { ObjectRecordOrderBySchema } from 'src/engine/core-modules/record-crud/zod-schemas/order-by.zod-schema';+import { generateRecordOrderBySchema } from 'src/engine/core-modules/record-crud/zod-schemas/order-by.zod-schema';import { generateRecordFilterSchema } from 'src/engine/core-modules/record-crud/zod-schemas/record-filter.zod-schema';export const generateFindToolInputSchema = (@@ -29,13 +29,7 @@ export const generateFindToolInputSchema = (.nonnegative().default(0).describe('Number of records to skip (default: 0)'),- orderBy: ObjectRecordOrderBySchema.describe(- 'Sort by field(s). ' +- 'Scalar fields: [{fieldName: "DescNullsLast"}]. ' +- 'Composite fields (name, address, currency, …): [{fieldName: {subFieldName: "AscNullsFirst"}}] — e.g. [{"name": {"firstName": "AscNullsFirst"}}]. ' +- 'Never use dot-notation keys like "name.firstName". ' +- 'Use DescNullsLast for top/largest, AscNullsFirst for bottom/smallest.',- ),+ orderBy: generateRecordOrderBySchema({ objectMetadata, restrictedFields }),select: z.array(z.string()).nonempty()diff --git a/packages/twenty-server/src/engine/core-modules/record-crud/zod-schemas/order-by.zod-schema.ts b/packages/twenty-server/src/engine/core-modules/record-crud/zod-schemas/order-by.zod-schema.tsindex 3ac0af0853c..13373e4868c 100644--- a/packages/twenty-server/src/engine/core-modules/record-crud/zod-schemas/order-by.zod-schema.ts+++ b/packages/twenty-server/src/engine/core-modules/record-crud/zod-schemas/order-by.zod-schema.ts@@ -1,36 +1,105 @@+import {+ compositeTypeDefinitions,+ FieldMetadataType,+ RelationType,+ type RestrictedFieldsPermissions,+} from 'twenty-shared/types';+import {+ isDefined,+ shouldExcludeFieldFromAgentToolSchema,+} from 'twenty-shared/utils';import { z } from 'zod';+import { type ObjectMetadataForToolSchema } from 'src/engine/core-modules/record-crud/types/object-metadata-for-tool-schema.type';+import { isCompositeFieldMetadataType } from 'src/engine/metadata-modules/field-metadata/utils/is-composite-field-metadata-type.util';+import { isFieldMetadataEntityOfType } from 'src/engine/utils/is-field-metadata-of-type.util';+export const OrderByDirectionEnum = z.enum(['AscNullsFirst','AscNullsLast','DescNullsFirst','DescNullsLast',]);-export const OrderByFieldValueSchema = z.union([- OrderByDirectionEnum,- z.record(z.string(), OrderByDirectionEnum),-]);-export const ObjectRecordOrderByItemSchema = z- .object({})- .catchall(OrderByFieldValueSchema)- .refine((obj) => Object.keys(obj).length === 1, {- message: 'Each orderBy item must specify exactly one field',- })- .describe(- 'Object with exactly ONE property. ' +- 'For scalar fields use a direction string: {"employees": "DescNullsLast"}. ' +- 'For composite fields (e.g. name, address, currency) use a nested object with the sub-field: {"name": {"firstName": "AscNullsFirst"}}. ' +- 'Never use dot-notation keys like "name.firstName".',- );--export const ObjectRecordOrderBySchema = z- .array(ObjectRecordOrderByItemSchema)- .optional()- .describe(- 'Array of sort criteria. Each item sorts by one field. ' +- 'Scalar fields: [{"employees": "DescNullsLast"}]. ' +- 'Composite fields (name, address, currency, …): [{"name": {"firstName": "AscNullsFirst"}}]. ' +- 'Use "DescNullsLast" for descending (top/largest), "AscNullsFirst" for ascending (bottom/smallest). ' +- 'Never use dot-notation keys like "name.firstName".',- );+// Mirrors the GraphQL orderBy input, so the shape advertised for each field+// (direction for scalars, sub-fields for composites) is the one the orderBy+// resolver accepts for this object+export const generateRecordOrderBySchema = ({+ objectMetadata,+ restrictedFields,+}: {+ objectMetadata: ObjectMetadataForToolSchema;+ restrictedFields?: RestrictedFieldsPermissions;+}): z.ZodTypeAny => {+ const orderByItemShape: Record<string, z.ZodTypeAny> = {};++ for (const field of objectMetadata.fields) {+ // System fields stay sortable: agents sort by createdAt, updatedAt and+ // position to get recent or first records+ if (+ shouldExcludeFieldFromAgentToolSchema({+ fieldName: field.name,+ isSystem: false,+ excludeId: false,+ })+ ) {+ continue;+ }++ if (restrictedFields?.[field.id]?.canRead === false) {+ continue;+ }++ const isRelationField =+ isFieldMetadataEntityOfType(field, FieldMetadataType.RELATION) ||+ isFieldMetadataEntityOfType(field, FieldMetadataType.MORPH_RELATION);++ if (isRelationField) {+ if (field.settings?.relationType === RelationType.MANY_TO_ONE) {+ orderByItemShape[`${field.name}Id`] = OrderByDirectionEnum.optional();+ }++ continue;+ }++ if (isCompositeFieldMetadataType(field.type)) {+ const compositeType = compositeTypeDefinitions.get(field.type);++ if (!isDefined(compositeType)) {+ continue;+ }++ const subFieldShape = Object.fromEntries(+ compositeType.properties+ .filter((property) => property.hidden !== true)+ .map((property) => [property.name, OrderByDirectionEnum.optional()]),+ );++ orderByItemShape[field.name] = z+ .object(subFieldShape)+ .strict()+ .optional();++ continue;+ }++ orderByItemShape[field.name] = OrderByDirectionEnum.optional();+ }++ const orderByItemSchema = z+ .object(orderByItemShape)+ .strict()+ .refine((item) => Object.keys(item).length === 1, {+ message: 'Each orderBy item must specify exactly one field',+ })+ .describe(+ 'Object with exactly ONE property. Scalar fields take a direction string; composite fields take an object with one sub-field. Never use dot-notation keys.',+ );++ return z+ .array(orderByItemSchema)+ .optional()+ .describe(+ 'Array of sort criteria, one field per item. Use "DescNullsLast" for descending (top/largest), "AscNullsFirst" for ascending (bottom/smallest).',+ );+};diff --git a/packages/twenty-server/src/engine/core-modules/tool-provider/providers/database-tool.provider.ts b/packages/twenty-server/src/engine/core-modules/tool-provider/providers/database-tool.provider.tsindex dda980e6ce1..e5a22a41e1b 100644--- a/packages/twenty-server/src/engine/core-modules/tool-provider/providers/database-tool.provider.ts+++ b/packages/twenty-server/src/engine/core-modules/tool-provider/providers/database-tool.provider.ts@@ -199,7 +199,7 @@ export class DatabaseToolProvider implements ToolProvider {this.i18nService,context.locale,),- description: `Search for ${objectMetadata.labelPlural} records using flexible filtering criteria. Supports exact matches, pattern matching, ranges, and null checks. Use limit/offset for pagination and orderBy for sorting. Filter fields are top-level arguments — pass each field as its own key (e.g. { id: { eq: "record-id" } }, or { name: { firstName: { ilike: "%ada%" } } }); do NOT wrap them in a "filter" object and do NOT place a bare operator like "ilike"/"eq" at the top level. Combine conditions with and/or/not. Returns an array of matching records with their full data, plus a "count" of total matches and a "hasNextPage" flag. When "hasNextPage" is true, more records match than were returned: continue with a higher offset (or increase the limit) before concluding a record is absent or answering count/enumeration questions.`,+ description: `Search for ${objectMetadata.labelPlural} records using flexible filtering criteria. Supports exact matches, pattern matching, ranges, and null checks. Use limit/offset for pagination and orderBy for sorting. Filter fields are top-level arguments — pass each field as its own key (e.g. { id: { eq: "record-id" } }; composite fields take their sub-field: { <field>: { <subField>: { ilike: "%ada%" } } }); do NOT wrap them in a "filter" object and do NOT place a bare operator like "ilike"/"eq" at the top level. Combine conditions with and/or/not. Returns an array of matching records with their full data, plus a "count" of total matches and a "hasNextPage" flag. When "hasNextPage" is true, more records match than were returned: continue with a higher offset (or increase the limit) before concluding a record is absent or answering count/enumeration questions.`,category: ToolCategory.DATABASE_CRUD,...(shouldIncludeSchema(`find_many_${snakePlural}`) && {inputSchema: toToolJsonSchema(