feat: Filter DSL for collections.list (#13442)

* feat: Filter DSL for collections.list

Adds the structured `filters` expression language to collections.list,
matching documents.list and documents.search. Supported fields are name,
createdAt, updatedAt, archivedAt, createdById and permission, each validated
against its column type at the input layer.

Deprecates the ad-hoc `query` and `statusFilter` params, which now translate
into filter leaves so that one code path serves both shapes, and returns a 400
when a caller combines them with `filters`.

Note that `query` matching is no longer accent-insensitive, as the unaccent
comparison is replaced by the shared iLike conversion.

* fix: Make filter expressions assignable to a JSON request body

Filters are sent as a JSON body, but `FilterCondition` and `FilterGroup` were
interfaces, which TypeScript does not give an implicit index signature, and
`FilterValue` admitted a `Date` that JSON cannot carry. Both stores worked
around this by asserting the request body to JSONObject, which suppressed
checking of every other field as well.

Declare the two shapes as type aliases and drop `Date` from the value union so
a filter type-checks against the request body directly, and remove the
assertions from the collection and document stores.

* feat: Restrict filter fields to a set of accepted values

Add an optional `values` set to a filter field definition, checked against
scalar and array values at the input layer so that an unsupported value returns
a 400 rather than an empty result or, for a field backed by a Postgres enum, a
database error. A field with a fixed value set is matched exactly, so pattern
operators are rejected for it in the same way as for non-text columns.

Apply it to `permission` on collections.list.

* refactor: Build the list_collections name filter with the filter DSL

The MCP tool carried its own copy of the unaccent name comparison that
collections.list used before it moved to the DSL. Build the clause with
buildWhere instead, so both paths match names the same way, and drop the
replacements plumbing it needed.
This commit is contained in:
Tom Moor authored and GitHub committed 2026-08-23 16:03:10 -04:00
1 parent 9a0a4eff2d
commit d551ead073
10 files changed
+454 -66

No files matched your search

+3 -5
View File
@@ -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<Collection> {
@action
fetchNamedPage = async (
request = "list",
options:
| (PaginationParams & { statusFilter: CollectionStatusFilter[] })
| undefined
options: (PaginationParams & { filters?: Filter[] }) | undefined
): Promise<Collection[]> => {
this.isFetching = true;
@@ -190,7 +188,7 @@ export default class CollectionsStore extends Store<Collection> {
fetchArchived = async (options?: PaginationParams): Promise<Collection[]> =>
this.fetchNamedPage("list", {
...options,
statusFilter: [CollectionStatusFilter.Archived],
filters: [{ field: "archivedAt", operator: "isNotNull" }],
});
get(id: string = ""): Collection | undefined {
+2 -3
View File
@@ -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<Document> {
@action
searchTitles = async (options?: SearchParams): Promise<SearchResult[]> => {
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<Document> {
@action
search = async (options: SearchParams): Promise<SearchResult[]> => {
const compactedOptions = omitBy(options, (o) => !o) as JSONObject;
const compactedOptions = omitBy(options, (o) => !o);
const res = await client.post("/documents.search", {
...compactedOptions,
});
@@ -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", () => {
+31 -29
View File
@@ -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<T.CollectionsListReq>) => {
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<Collection>(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,
}),
]);
+34 -2
View File
@@ -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<typeof CollectionsUpdateSchema>;
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<typeof CollectionsListSchema>;
+23
View File
@@ -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();
+6 -5
View File
@@ -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<Collection>
buildWhere<Collection>({
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"],
+21
View File
@@ -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", () => {
+14 -5
View File
@@ -39,7 +39,10 @@ export type ComparisonOperator = z.infer<typeof ComparisonOperator>;
export const LogicalOperator = z.enum(["AND", "OR"]);
export type LogicalOperator = z.infer<typeof LogicalOperator>;
/** 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<typeof FilterValue>;
/**
* 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<F extends string = string> {
export type FilterCondition<F extends string = string> = {
/** The field being compared. */
field: F;
@@ -63,21 +69,24 @@ export interface FilterCondition<F extends string = string> {
/** 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<F extends string = string> {
export type FilterGroup<F extends string = string> = {
/** How the nested expressions are combined. */
operator: LogicalOperator;
/** The nested expressions, each a condition or a further group. */
filters: Array<FilterCondition<F> | FilterGroup<F>>;
}
};
/**
* A filter expression: either a single condition or a group of them.
+1 -17
View File
@@ -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: