diff --git a/app/stores/CollectionsStore.ts b/app/stores/CollectionsStore.ts index 07c0d6fffc..f8f69c4f48 100644 --- a/app/stores/CollectionsStore.ts +++ b/app/stores/CollectionsStore.ts @@ -1,9 +1,9 @@ import invariant from "invariant"; import { isEmpty, orderBy, sortBy } from "es-toolkit/compat"; import { computed, action, runInAction } from "mobx"; +import type { Filter } from "@shared/helpers/FilterHelper"; import { CollectionPermission, - CollectionStatusFilter, type FileOperationFormat, SubscriptionType, } from "@shared/types"; @@ -166,9 +166,7 @@ export default class CollectionsStore extends Store { @action fetchNamedPage = async ( request = "list", - options: - | (PaginationParams & { statusFilter: CollectionStatusFilter[] }) - | undefined + options: (PaginationParams & { filters?: Filter[] }) | undefined ): Promise => { this.isFetching = true; @@ -190,7 +188,7 @@ export default class CollectionsStore extends Store { fetchArchived = async (options?: PaginationParams): Promise => this.fetchNamedPage("list", { ...options, - statusFilter: [CollectionStatusFilter.Archived], + filters: [{ field: "archivedAt", operator: "isNotNull" }], }); get(id: string = ""): Collection | undefined { diff --git a/app/stores/DocumentsStore.ts b/app/stores/DocumentsStore.ts index 611ce9bf6f..0d05991bce 100644 --- a/app/stores/DocumentsStore.ts +++ b/app/stores/DocumentsStore.ts @@ -11,7 +11,6 @@ import type { Filter } from "@shared/helpers/FilterHelper"; import { subtractDate } from "@shared/utils/date"; import { bytesToHumanReadable } from "@shared/utils/files"; import naturalSort from "@shared/utils/naturalSort"; -import type { JSONObject } from "@shared/types"; import type RootStore from "~/stores/RootStore"; import Store from "~/stores/base/Store"; import Document from "~/models/Document"; @@ -454,7 +453,7 @@ export default class DocumentsStore extends Store { @action searchTitles = async (options?: SearchParams): Promise => { - const compactedOptions = omitBy(options, (o) => !o) as JSONObject; + const compactedOptions = omitBy(options, (o) => !o); const res = await client.post("/documents.search_titles", { ...compactedOptions, }); @@ -485,7 +484,7 @@ export default class DocumentsStore extends Store { @action search = async (options: SearchParams): Promise => { - const compactedOptions = omitBy(options, (o) => !o) as JSONObject; + const compactedOptions = omitBy(options, (o) => !o); const res = await client.post("/documents.search", { ...compactedOptions, }); diff --git a/server/routes/api/collections/collections.test.ts b/server/routes/api/collections/collections.test.ts index c1a8f86523..cc0e4fb76a 100644 --- a/server/routes/api/collections/collections.test.ts +++ b/server/routes/api/collections/collections.test.ts @@ -220,6 +220,325 @@ describe("#collections.list", () => { expect(afterArchiveRes.status).toEqual(200); expect(afterArchiveBody.data).toHaveLength(0); }); + + it("should filter by name ignoring case", async () => { + const user = await buildUser(); + const collection = await buildCollection({ + name: "Product Design", + teamId: user.teamId, + userId: user.id, + }); + await buildCollection({ + name: "Something else", + teamId: user.teamId, + userId: user.id, + }); + + const res = await server.post("/api/collections.list", user, { + body: { + filters: [{ field: "name", operator: "contains", value: "DUCT DES" }], + }, + }); + const body = await res.json(); + expect(res.status).toEqual(200); + expect(body.data).toHaveLength(1); + expect(body.data[0].id).toEqual(collection.id); + expect(body.pagination.total).toEqual(1); + }); + + it("should filter by name with the deprecated query param", async () => { + const user = await buildUser(); + const collection = await buildCollection({ + name: "Product Design", + teamId: user.teamId, + userId: user.id, + }); + await buildCollection({ + name: "Something else", + teamId: user.teamId, + userId: user.id, + }); + + const res = await server.post("/api/collections.list", user, { + body: { + query: "duct des", + }, + }); + const body = await res.json(); + expect(res.status).toEqual(200); + expect(body.data).toHaveLength(1); + expect(body.data[0].id).toEqual(collection.id); + }); + + it("should treat wildcards in a name filter literally", async () => { + const user = await buildUser(); + await buildCollection({ + name: "Engineering", + teamId: user.teamId, + userId: user.id, + }); + + const res = await server.post("/api/collections.list", user, { + body: { + filters: [{ field: "name", operator: "contains", value: "%" }], + }, + }); + const body = await res.json(); + expect(res.status).toEqual(200); + expect(body.data).toHaveLength(0); + }); + + it("should exclude archived collections unless the filter targets archivedAt", async () => { + const user = await buildUser(); + const collection = await buildCollection({ + name: "Engineering", + teamId: user.teamId, + userId: user.id, + }); + await buildCollection({ + name: "Engineering archive", + teamId: user.teamId, + userId: user.id, + archivedAt: new Date(), + }); + + const res = await server.post("/api/collections.list", user, { + body: { + filters: [ + { field: "name", operator: "startsWith", value: "Engineering" }, + ], + }, + }); + const body = await res.json(); + expect(res.status).toEqual(200); + expect(body.data).toHaveLength(1); + expect(body.data[0].id).toEqual(collection.id); + }); + + it("should include archived collections when filtering on archivedAt", async () => { + const team = await buildTeam(); + const admin = await buildAdmin({ teamId: team.id }); + const collection = await buildCollection({ + teamId: team.id, + archivedAt: new Date(), + }); + await buildCollection({ + teamId: team.id, + userId: admin.id, + }); + + const res = await server.post("/api/collections.list", admin, { + body: { + filters: [{ field: "archivedAt", operator: "isNotNull" }], + }, + }); + const body = await res.json(); + expect(res.status).toEqual(200); + expect(body.data).toHaveLength(1); + expect(body.data[0].id).toEqual(collection.id); + expect(body.data[0].archivedBy).toBeTruthy(); + expect(body.data[0].archivedBy.id).toBe(collection.archivedById); + }); + + it("should combine a name filter with an archivedAt filter", async () => { + const team = await buildTeam(); + const admin = await buildAdmin({ teamId: team.id }); + const collection = await buildCollection({ + name: "Engineering", + teamId: team.id, + userId: admin.id, + archivedAt: new Date(), + }); + await buildCollection({ + name: "Engineering", + teamId: team.id, + userId: admin.id, + }); + + const res = await server.post("/api/collections.list", admin, { + body: { + filters: [ + { field: "archivedAt", operator: "isNotNull" }, + { field: "name", operator: "contains", value: "engineer" }, + ], + }, + }); + const body = await res.json(); + expect(res.status).toEqual(200); + expect(body.data).toHaveLength(1); + expect(body.data[0].id).toEqual(collection.id); + }); + + it("should include archived private collections for admin when filtering on archivedAt", async () => { + const team = await buildTeam(); + const admin = await buildAdmin({ teamId: team.id }); + const collection = await buildCollection({ + teamId: team.id, + permission: null, + archivedAt: new Date(), + }); + + const res = await server.post("/api/collections.list", admin, { + body: { + filters: [{ field: "archivedAt", operator: "isNotNull" }], + }, + }); + const body = await res.json(); + expect(res.status).toEqual(200); + expect(body.data).toHaveLength(1); + expect(body.data[0].id).toEqual(collection.id); + expect(body.policies[0].abilities.restore).toBeTruthy(); + }); + + it("should include private collections for admin whenever the filter targets archivedAt", async () => { + // Matches the existing `includeListOnly` behavior, which already lets an + // admin list private collections they are not a member of. + const team = await buildTeam(); + const admin = await buildAdmin({ teamId: team.id }); + await buildCollection({ + teamId: team.id, + permission: null, + archivedAt: new Date(), + }); + await buildCollection({ + teamId: team.id, + permission: null, + }); + + const res = await server.post("/api/collections.list", admin, { + body: { + filters: [ + { + operator: "OR", + filters: [ + { field: "archivedAt", operator: "isNotNull" }, + { field: "archivedAt", operator: "isNull" }, + ], + }, + ], + }, + }); + const body = await res.json(); + expect(res.status).toEqual(200); + expect(body.data).toHaveLength(2); + }); + + it("should not include archived private collections for member when filtering on archivedAt", async () => { + const team = await buildTeam(); + const user = await buildUser({ teamId: team.id }); + await buildCollection({ + teamId: team.id, + permission: null, + archivedAt: new Date(), + }); + + const res = await server.post("/api/collections.list", user, { + body: { + filters: [{ field: "archivedAt", operator: "isNotNull" }], + }, + }); + const body = await res.json(); + expect(res.status).toEqual(200); + expect(body.data).toHaveLength(0); + }); + + it("should filter by createdById", async () => { + const team = await buildTeam(); + const user = await buildUser({ teamId: team.id }); + const other = await buildUser({ teamId: team.id }); + const collection = await buildCollection({ + teamId: team.id, + userId: user.id, + }); + await buildCollection({ + teamId: team.id, + userId: other.id, + }); + + const res = await server.post("/api/collections.list", user, { + body: { + filters: [{ field: "createdById", operator: "eq", value: user.id }], + }, + }); + const body = await res.json(); + expect(res.status).toEqual(200); + expect(body.data).toHaveLength(1); + expect(body.data[0].id).toEqual(collection.id); + }); + + it("should filter private collections by permission", async () => { + const user = await buildUser(); + const collection = await buildCollection({ + teamId: user.teamId, + userId: user.id, + permission: null, + }); + await buildCollection({ + teamId: user.teamId, + userId: user.id, + permission: CollectionPermission.ReadWrite, + }); + + const res = await server.post("/api/collections.list", user, { + body: { + filters: [{ field: "permission", operator: "isNull" }], + }, + }); + const body = await res.json(); + expect(res.status).toEqual(200); + expect(body.data).toHaveLength(1); + expect(body.data[0].id).toEqual(collection.id); + }); + + it("should not allow filtering on an unknown permission", async () => { + const user = await buildUser(); + const res = await server.post("/api/collections.list", user, { + body: { + filters: [{ field: "permission", operator: "eq", value: "manage" }], + }, + }); + expect(res.status).toEqual(400); + }); + + it("should not allow filters combined with deprecated parameters", async () => { + const user = await buildUser(); + + const withQuery = await server.post("/api/collections.list", user, { + body: { + query: "test", + filters: [{ field: "name", operator: "contains", value: "test" }], + }, + }); + expect(withQuery.status).toEqual(400); + + const withStatusFilter = await server.post("/api/collections.list", user, { + body: { + statusFilter: [CollectionStatusFilter.Archived], + filters: [{ field: "archivedAt", operator: "isNotNull" }], + }, + }); + expect(withStatusFilter.status).toEqual(400); + }); + + it("should not allow filtering on an unknown field", async () => { + const user = await buildUser(); + const res = await server.post("/api/collections.list", user, { + body: { + filters: [{ field: "deletedAt", operator: "isNotNull" }], + }, + }); + expect(res.status).toEqual(400); + }); + + it("should not allow pattern matching on a non-text field", async () => { + const user = await buildUser(); + const res = await server.post("/api/collections.list", user, { + body: { + filters: [{ field: "createdById", operator: "contains", value: "abc" }], + }, + }); + expect(res.status).toEqual(400); + }); }); describe("#collections.import", () => { diff --git a/server/routes/api/collections/collections.ts b/server/routes/api/collections/collections.ts index c1073069d3..4a9e186e70 100644 --- a/server/routes/api/collections/collections.ts +++ b/server/routes/api/collections/collections.ts @@ -3,6 +3,7 @@ import { randomUUID } from "node:crypto"; import { truncate } from "es-toolkit/compat"; import type { WhereOptions } from "sequelize"; import { Sequelize, Op } from "sequelize"; +import type { Filter } from "@shared/helpers/FilterHelper"; import { CollectionPermission, CollectionStatusFilter, @@ -30,6 +31,11 @@ import { Document, Import, } from "@server/models"; +import { + buildWhere, + combineFilters, + hasFieldInFilter, +} from "@server/models/helpers/Filters"; import { authorize } from "@server/policies"; import { presentCollection, @@ -735,7 +741,12 @@ router.post( pagination(), transaction(), async (ctx: APIContext) => { - const { includeListOnly, query, statusFilter } = ctx.input.body; + const { + includeListOnly, + query, + statusFilter, + filters: rawFilters, + } = ctx.input.body; const { user } = ctx.state.auth; const { transaction } = ctx.state; const collectionIds = await user.collectionIds({ transaction }); @@ -753,11 +764,24 @@ router.post( ], }; - const includeArchived = !!statusFilter?.includes( - CollectionStatusFilter.Archived - ); + // The schema rejects callers that combine `filters` with the deprecated + // top-level params, so at most one of the two shapes is set. + const legacyLeaves: Filter[] = []; + if (query) { + legacyLeaves.push({ field: "name", operator: "contains", value: query }); + } + if (statusFilter?.includes(CollectionStatusFilter.Archived)) { + legacyLeaves.push({ field: "archivedAt", operator: "isNotNull" }); + } + const filter = combineFilters(rawFilters ?? legacyLeaves); - if (!statusFilter) { + // Results can contain archived collections once the caller targets + // archivedAt themselves, so hydrate the archiving user for presentation. + const includeArchived = + filter !== undefined && hasFieldInFilter(filter, "archivedAt"); + + // Exclude archived collections unless the caller targets archivedAt. + if (statusFilter === undefined && !includeArchived) { where[Op.and].push({ archivedAt: { [Op.eq]: null } }); } @@ -767,29 +791,10 @@ router.post( where[Op.and].push({ id: collectionIds }); } - if (query) { - where[Op.and].push( - Sequelize.literal(`unaccent(LOWER(name)) like unaccent(LOWER(:query))`) - ); + if (filter) { + where[Op.and].push(buildWhere(filter)); } - const statusQuery = []; - if (includeArchived) { - statusQuery.push({ - archivedAt: { - [Op.ne]: null, - }, - }); - } - - if (statusQuery.length) { - where[Op.and].push({ - [Op.or]: statusQuery, - }); - } - - const replacements = { query: QueryHelper.likeContains(query ?? "") }; - const [collections, total] = await Promise.all([ Collection.scope( includeArchived @@ -804,7 +809,6 @@ router.post( } ).findAll({ where, - replacements, order: [ Sequelize.literal('"collection"."index" collate "C"'), ["updatedAt", "DESC"], @@ -815,8 +819,6 @@ router.post( }), Collection.count({ where, - // @ts-expect-error Types are incorrect for count - replacements, transaction, }), ]); diff --git a/server/routes/api/collections/schema.ts b/server/routes/api/collections/schema.ts index e2410d4d9a..47e7923d37 100644 --- a/server/routes/api/collections/schema.ts +++ b/server/routes/api/collections/schema.ts @@ -1,5 +1,6 @@ import { isUndefined } from "es-toolkit/compat"; import { z } from "zod"; +import { createFilterSchema } from "@shared/helpers/FilterHelper"; import { CollectionPermission, CollectionStatusFilter, @@ -215,16 +216,47 @@ export const CollectionsUpdateSchema = BaseSchema.extend({ export type CollectionsUpdateReq = z.infer; +const collectionListFilter = createFilterSchema({ + name: "string", + createdAt: "date", + updatedAt: "date", + archivedAt: "date", + createdById: "uuid", + permission: { + kind: "string", + operators: ["eq", "neq", "in", "notIn", "isNull", "isNotNull"], + values: Object.values(CollectionPermission), + }, +} as const); + export const CollectionsListSchema = BaseSchema.extend({ body: z.object({ includeListOnly: z.boolean().prefault(false), + /** + * Filter results by collection name. + * @deprecated use `filters` with field `name` and operator `contains` instead. + */ query: z.string().optional(), - /** Collection statuses to include in results */ + /** + * Collection statuses to include in results. + * @deprecated use `filters` with field `archivedAt` instead. + */ statusFilter: z.enum(CollectionStatusFilter).array().optional(), + + /** List of filter expressions. Implicit AND between top-level entries. */ + filters: collectionListFilter.FilterListSchema.optional(), }), -}); +}).refine( + (req) => + req.body.filters === undefined || + (req.body.query === undefined && req.body.statusFilter === undefined), + { + message: + "filters cannot be combined with deprecated parameters query or statusFilter", + } +); export type CollectionsListReq = z.infer; diff --git a/server/tools/collections.test.ts b/server/tools/collections.test.ts index c23c94e413..f5f2b2be8c 100644 --- a/server/tools/collections.test.ts +++ b/server/tools/collections.test.ts @@ -31,6 +31,29 @@ describe("collection tools", () => { expect(match!.url).toMatch(/^https?:\/\//); }); + it("list_collections filters by name ignoring case", async () => { + const { user, accessToken } = await buildOAuthUser(); + const collection = await buildCollection({ + name: "Product Design", + teamId: user.teamId, + userId: user.id, + }); + const other = await buildCollection({ + name: "Something else", + teamId: user.teamId, + userId: user.id, + }); + + const res = await callMcpTool(server, accessToken, "list_collections", { + query: "duct des", + }); + const data = parseMcpListContent<{ id: string }>(res?.result?.content); + + const ids = data.map((c) => c.id); + expect(ids).toContain(collection.id); + expect(ids).not.toContain(other.id); + }); + it("list_collections does not return collections from another team", async () => { const { accessToken } = await buildOAuthUser(); const otherUser = await buildUser(); diff --git a/server/tools/collections.ts b/server/tools/collections.ts index 9f973c7873..5ddcdc411e 100644 --- a/server/tools/collections.ts +++ b/server/tools/collections.ts @@ -2,8 +2,8 @@ import { z } from "zod"; import { Sequelize, Op, type WhereOptions } from "sequelize"; import { type McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"; import { Collection, Team } from "@server/models"; +import { buildWhere } from "@server/models/helpers/Filters"; import { sequelize } from "@server/storage/database"; -import { QueryHelper } from "@server/storage/QueryHelper"; import { authorize } from "@server/policies"; import { presentCollection as presentCollectionBase } from "@server/presenters"; import AuthenticationHelper from "@shared/helpers/AuthenticationHelper"; @@ -89,9 +89,11 @@ export function collectionTools(server: McpServer, scopes: string[]) { if (query) { and.push( - Sequelize.literal( - `unaccent(LOWER(name)) like unaccent(LOWER(:query))` - ) as unknown as WhereOptions + buildWhere({ + field: "name", + operator: "contains", + value: query, + }) ); } @@ -104,7 +106,6 @@ export function collectionTools(server: McpServer, scopes: string[]) { method: ["withMembership", user.id], }).findAll({ where, - replacements: { query: QueryHelper.likeContains(query ?? "") }, order: [ Sequelize.literal('"collection"."index" collate "C"'), ["updatedAt", "DESC"], diff --git a/shared/helpers/FilterHelper.test.ts b/shared/helpers/FilterHelper.test.ts index 12d29c2572..a235968a8c 100644 --- a/shared/helpers/FilterHelper.test.ts +++ b/shared/helpers/FilterHelper.test.ts @@ -315,6 +315,27 @@ describe("createFilterSchema value allowlists", () => { }).success ).toBe(true); }); + + it("still allows null operators with no value", () => { + expect( + EnumSchema.safeParse({ + field: "role", + operator: "isNull", + }).success + ).toBe(true); + }); + + it("rejects a disallowed value nested inside a group", () => { + expect( + EnumSchema.safeParse({ + operator: "AND", + filters: [ + { field: "title", operator: "eq", value: "x" }, + { field: "role", operator: "eq", value: "superuser" }, + ], + }).success + ).toBe(false); + }); }); describe("createFilterSchema node limit", () => { diff --git a/shared/helpers/FilterHelper.ts b/shared/helpers/FilterHelper.ts index a36cd3655b..1e460da5ab 100644 --- a/shared/helpers/FilterHelper.ts +++ b/shared/helpers/FilterHelper.ts @@ -39,7 +39,10 @@ export type ComparisonOperator = z.infer; export const LogicalOperator = z.enum(["AND", "OR"]); export type LogicalOperator = z.infer; -/** The value a filter condition compares against. */ +/** + * The value a filter condition compares against. Filters travel over the wire + * as JSON, so the value is limited to JSON types. + */ export const FilterValue = z.union([ z.string(), z.number(), @@ -52,9 +55,12 @@ export type FilterValue = z.infer; /** * A single comparison against one field, the leaf of a filter expression. * + * Declared as a type alias rather than an interface so that TypeScript infers + * an index signature and a filter stays assignable to a JSON request body. + * * @typeParam F the field names the condition may reference. */ -export interface FilterCondition { +export type FilterCondition = { /** The field being compared. */ field: F; @@ -63,21 +69,24 @@ export interface FilterCondition { /** The value to compare against, omitted for `isNull` and `isNotNull`. */ value?: FilterValue; -} +}; /** * A set of filter expressions combined under one logical operator. Groups may * contain other groups, forming a tree. * + * Declared as a type alias rather than an interface so that TypeScript infers + * an index signature and a filter stays assignable to a JSON request body. + * * @typeParam F the field names the nested conditions may reference. */ -export interface FilterGroup { +export type FilterGroup = { /** How the nested expressions are combined. */ operator: LogicalOperator; /** The nested expressions, each a condition or a further group. */ filters: Array | FilterGroup>; -} +}; /** * A filter expression: either a single condition or a group of them. diff --git a/yarn.lock b/yarn.lock index d8130a724a..f834e7e99f 100644 --- a/yarn.lock +++ b/yarn.lock @@ -5482,23 +5482,7 @@ __metadata: languageName: node linkType: hard -"@rollup/pluginutils@npm:^5.0.1": - version: 5.3.0 - resolution: "@rollup/pluginutils@npm:5.3.0" - dependencies: - "@types/estree": "npm:^1.0.0" - estree-walker: "npm:^2.0.2" - picomatch: "npm:^4.0.2" - peerDependencies: - rollup: ^1.20.0||^2.0.0||^3.0.0||^4.0.0 - peerDependenciesMeta: - rollup: - optional: true - checksum: 10c0/001834bf62d7cf5bac424d2617c113f7f7d3b2bf3c1778cbcccb72cdc957b68989f8e7747c782c2b911f1dde8257f56f8ac1e779e29e74e638e3f1e2cac2bcd0 - languageName: node - linkType: hard - -"@rollup/pluginutils@npm:^5.4.0": +"@rollup/pluginutils@npm:^5.0.1, @rollup/pluginutils@npm:^5.4.0": version: 5.4.0 resolution: "@rollup/pluginutils@npm:5.4.0" dependencies: