Skip to content

armgit / papra

Public Imported from GitHub
0

The minimalistic document archiving platform.

feat(documents): add batch trash endpoint (#1074)

Corentin Thomassete2e7fd4f1d2c
diff --git a/.changeset/clear-items-clean.md b/.changeset/clear-items-clean.md
new file mode 100644
index 00000000..ec85cd3c
--- /dev/null
+++ b/.changeset/clear-items-clean.md
@@ -0,0 +1,5 @@
+---
+"@papra/app": patch
+---
+
+Limited search query to 1024 characters
diff --git a/.changeset/strong-cooks-see.md b/.changeset/strong-cooks-see.md
new file mode 100644
index 00000000..bcca2826
--- /dev/null
+++ b/.changeset/strong-cooks-see.md
@@ -0,0 +1,6 @@
+---
+"@papra/api-sdk": minor
+"@papra/app": patch
+---
+
+Add batch document trash endpoint
diff --git a/apps/papra-server/src/modules/app/server.routes.ts b/apps/papra-server/src/modules/app/server.routes.ts
index ee089851..66143a7c 100644
--- a/apps/papra-server/src/modules/app/server.routes.ts
+++ b/apps/papra-server/src/modules/app/server.routes.ts
@@ -4,6 +4,7 @@ import { registerApiKeysRoutes } from '../api-keys/api-keys.routes';
import { registerConfigRoutes } from '../config/config.routes';
import { registerCustomPropertiesRoutes } from '../custom-properties/custom-properties.routes';
import { registerDocumentActivityRoutes } from '../documents/document-activity/document-activity.routes';
+import { registerDocumentsBatchRoutes } from '../documents/documents-batch/documents-batch.routes';
import { registerDocumentsRoutes } from '../documents/documents.routes';
import { registerIntakeEmailsRoutes } from '../intake-emails/intake-emails.routes';
import { registerInvitationsRoutes } from '../invitations/invitations.routes';
@@ -25,6 +26,7 @@ export function registerRoutes(context: RouteDefinitionContext) {
registerUsersRoutes(context);
registerOrganizationsRoutes(context);
registerDocumentsRoutes(context);
+ registerDocumentsBatchRoutes(context);
registerTagsRoutes(context);
registerTaggingRulesRoutes(context);
registerApiKeysRoutes(context);
diff --git a/apps/papra-server/src/modules/documents/document-search/database-fts5/database-fts5.document-search-provider.ts b/apps/papra-server/src/modules/documents/document-search/database-fts5/database-fts5.document-search-provider.ts
index d2457c92..ad8becb7 100644
--- a/apps/papra-server/src/modules/documents/document-search/database-fts5/database-fts5.document-search-provider.ts
+++ b/apps/papra-server/src/modules/documents/document-search/database-fts5/database-fts5.document-search-provider.ts
@@ -18,6 +18,10 @@ export function createDatabaseFts5DocumentSearchServices({ db }: { db: Database
};
},
+ getDocumentIdsMatchingQuery: async ({ searchQuery, organizationId }) => {
+ return documentsSearchRepository.getDocumentIdsMatchingQuery({ organizationId, searchQuery });
+ },
+
indexDocuments: async ({ documents }) => {
await documentsSearchRepository.indexDocuments({ documents });
},
diff --git a/apps/papra-server/src/modules/documents/document-search/database-fts5/database-fts5.repository.ts b/apps/papra-server/src/modules/documents/document-search/database-fts5/database-fts5.repository.ts
index 0c6ecd52..6bae5fa8 100644
--- a/apps/papra-server/src/modules/documents/document-search/database-fts5/database-fts5.repository.ts
+++ b/apps/papra-server/src/modules/documents/document-search/database-fts5/database-fts5.repository.ts
@@ -14,6 +14,7 @@ export type DocumentSearchRepository = ReturnType<typeof createDocumentSearchRep
export function createDocumentSearchRepository({ db }: { db: Database }) {
return injectArguments({
searchOrganizationDocuments,
+ getDocumentIdsMatchingQuery,
indexDocuments,
updateDocuments,
deleteDocuments,
@@ -57,6 +58,22 @@ async function searchOrganizationDocuments({ organizationId, searchQuery, pageIn
return { documents, documentsCount };
}
+async function getDocumentIdsMatchingQuery({ organizationId, searchQuery, db, now = new Date() }: { organizationId: string; searchQuery: string; db: Database; now?: Date }) {
+ const customPropertyDefinitions = await db
+ .select()
+ .from(customPropertyDefinitionsTable)
+ .where(eq(customPropertyDefinitionsTable.organizationId, organizationId));
+
+ const { searchWhereClause } = makeSearchWhereClause({ organizationId, query: searchQuery, db, now, customPropertyDefinitions });
+
+ const rows = await db
+ .selectDistinct({ id: documentsTable.id })
+ .from(documentsTable)
+ .where(searchWhereClause);
+
+ return { documentIds: rows.map(row => row.id) };
+}
+
async function indexDocuments({ documents, db }: { documents: DocumentSearchableData[]; db: Database }) {
if (documents.length === 0) {
return;
diff --git a/apps/papra-server/src/modules/documents/document-search/document-search.types.ts b/apps/papra-server/src/modules/documents/document-search/document-search.types.ts
index cf801e77..4963a14e 100644
--- a/apps/papra-server/src/modules/documents/document-search/document-search.types.ts
+++ b/apps/papra-server/src/modules/documents/document-search/document-search.types.ts
@@ -27,6 +27,11 @@ export type DocumentSearchServices = {
pageSize: number;
}) => Promise<DocumentSearchResult>;
+ getDocumentIdsMatchingQuery: (args: {
+ searchQuery: string;
+ organizationId: string;
+ }) => Promise<{ documentIds: string[] }>;
+
indexDocuments: (args: { documents: DocumentSearchableData[] }) => Promise<void>;
updateDocuments: (args: { updates: DocumentUpdate[] }) => Promise<void>;
deleteDocuments: (args: { documentIds: string[] }) => Promise<void>;
diff --git a/apps/papra-server/src/modules/documents/document-search/events/sync-document-search.handlers.test.ts b/apps/papra-server/src/modules/documents/document-search/events/sync-document-search.handlers.test.ts
index 31853029..91d6a1cb 100644
--- a/apps/papra-server/src/modules/documents/document-search/events/sync-document-search.handlers.test.ts
+++ b/apps/papra-server/src/modules/documents/document-search/events/sync-document-search.handlers.test.ts
@@ -9,6 +9,7 @@ import { registerSyncDocumentSearchEventHandlers } from './sync-document-search.
function createTestSearchServices() {
const methodsArgs = {
searchDocuments: [] as Parameters<DocumentSearchServices['searchDocuments']>[0][],
+ getDocumentIdsMatchingQuery: [] as Parameters<DocumentSearchServices['getDocumentIdsMatchingQuery']>[0][],
indexDocuments: [] as Parameters<DocumentSearchServices['indexDocuments']>[0][],
updateDocuments: [] as Parameters<DocumentSearchServices['updateDocuments']>[0][],
deleteDocuments: [] as Parameters<DocumentSearchServices['deleteDocuments']>[0][],
@@ -20,6 +21,10 @@ function createTestSearchServices() {
methodsArgs.searchDocuments.push(args);
return { documents: [], documentsCount: 0 };
},
+ getDocumentIdsMatchingQuery: async (args) => {
+ methodsArgs.getDocumentIdsMatchingQuery.push(args);
+ return { documentIds: [] };
+ },
indexDocuments: async (args) => {
methodsArgs.indexDocuments.push(args);
},
@@ -77,6 +82,7 @@ describe('sync-document-search event handlers', () => {
expect(documentSearchServices.getMethodsArguments()).to.eql({
searchDocuments: [],
+ getDocumentIdsMatchingQuery: [],
indexDocuments: [{ documents: [document] }],
updateDocuments: [],
deleteDocuments: [],
@@ -126,6 +132,7 @@ describe('sync-document-search event handlers', () => {
expect(documentSearchServices.getMethodsArguments()).to.eql({
searchDocuments: [],
+ getDocumentIdsMatchingQuery: [],
indexDocuments: [],
updateDocuments: [{
updates: [{
@@ -157,6 +164,7 @@ describe('sync-document-search event handlers', () => {
expect(documentSearchServices.getMethodsArguments()).to.eql({
searchDocuments: [],
+ getDocumentIdsMatchingQuery: [],
indexDocuments: [],
updateDocuments: [{
updates: [{
@@ -188,6 +196,7 @@ describe('sync-document-search event handlers', () => {
expect(documentSearchServices.getMethodsArguments()).to.eql({
searchDocuments: [],
+ getDocumentIdsMatchingQuery: [],
indexDocuments: [],
updateDocuments: [{
updates: [{
@@ -218,6 +227,7 @@ describe('sync-document-search event handlers', () => {
expect(documentSearchServices.getMethodsArguments()).to.eql({
searchDocuments: [],
+ getDocumentIdsMatchingQuery: [],
indexDocuments: [],
updateDocuments: [],
deleteDocuments: [{ documentIds: ['doc-1'] }],
@@ -298,6 +308,7 @@ describe('sync-document-search event handlers', () => {
expect(documentSearchServices.getMethodsArguments()).to.eql({
searchDocuments: [],
+ getDocumentIdsMatchingQuery: [],
indexDocuments: [{ documents: [document] }],
updateDocuments: [
{
diff --git a/apps/papra-server/src/modules/documents/documents-batch/documents-batch.constants.ts b/apps/papra-server/src/modules/documents/documents-batch/documents-batch.constants.ts
new file mode 100644
index 00000000..0842f4e1
--- /dev/null
+++ b/apps/papra-server/src/modules/documents/documents-batch/documents-batch.constants.ts
@@ -0,0 +1 @@
+export const BATCH_MAX_DOCUMENTS = 1000;
diff --git a/apps/papra-server/src/modules/documents/documents-batch/documents-batch.routes.ts b/apps/papra-server/src/modules/documents/documents-batch/documents-batch.routes.ts
new file mode 100644
index 00000000..bcb31f20
--- /dev/null
+++ b/apps/papra-server/src/modules/documents/documents-batch/documents-batch.routes.ts
@@ -0,0 +1,47 @@
+import type { RouteDefinitionContext } from '../../app/server.types';
+import * as v from 'valibot';
+import { requireAuthentication } from '../../app/auth/auth.middleware';
+import { getUser } from '../../app/auth/auth.models';
+import { organizationIdSchema } from '../../organizations/organization.schemas';
+import { createOrganizationsRepository } from '../../organizations/organizations.repository';
+import { ensureUserIsInOrganization } from '../../organizations/organizations.usecases';
+import { validateJsonBody, validateParams } from '../../shared/validation/validation';
+import { createDocumentsRepository } from '../documents.repository';
+import { batchTrashBodySchema } from './documents-batch.schemas';
+import { trashDocumentsBatch } from './documents-batch.usecases';
+
+export function registerDocumentsBatchRoutes(context: RouteDefinitionContext) {
+ setupBatchTrashDocumentsRoute(context);
+}
+
+function setupBatchTrashDocumentsRoute({ app, db, eventServices, documentSearchServices }: RouteDefinitionContext) {
+ app.post(
+ '/api/organizations/:organizationId/documents/batch/trash',
+ requireAuthentication({ apiKeyPermissions: ['documents:delete'] }),
+ validateParams(v.strictObject({
+ organizationId: organizationIdSchema,
+ })),
+ validateJsonBody(batchTrashBodySchema),
+ async (context) => {
+ const { userId } = getUser({ context });
+ const { organizationId } = context.req.valid('param');
+ const { filter } = context.req.valid('json');
+
+ const documentsRepository = createDocumentsRepository({ db });
+ const organizationsRepository = createOrganizationsRepository({ db });
+
+ await ensureUserIsInOrganization({ userId, organizationId, organizationsRepository });
+
+ await trashDocumentsBatch({
+ filter,
+ organizationId,
+ userId,
+ documentsRepository,
+ documentSearchServices,
+ eventServices,
+ });
+
+ return context.body(null, 204);
+ },
+ );
+}
diff --git a/apps/papra-server/src/modules/documents/documents-batch/documents-batch.schemas.test.ts b/apps/papra-server/src/modules/documents/documents-batch/documents-batch.schemas.test.ts
new file mode 100644
index 00000000..54b6a007
--- /dev/null
+++ b/apps/papra-server/src/modules/documents/documents-batch/documents-batch.schemas.test.ts
@@ -0,0 +1,74 @@
+import * as v from 'valibot';
+import { describe, expect, test } from 'vitest';
+import { BATCH_MAX_DOCUMENTS } from './documents-batch.constants';
+import { batchTrashBodySchema } from './documents-batch.schemas';
+
+describe('documents-batch.schemas', () => {
+ describe('batchTrashBodySchema', () => {
+ test('parses a body with documentIds filter', () => {
+ const result = v.parse(batchTrashBodySchema, {
+ filter: { documentIds: ['doc_aaaaaaaaaaaaaaaaaaaaaaaa', 'doc_bbbbbbbbbbbbbbbbbbbbbbbb'] },
+ });
+
+ expect(result).toEqual({
+ filter: { documentIds: ['doc_aaaaaaaaaaaaaaaaaaaaaaaa', 'doc_bbbbbbbbbbbbbbbbbbbbbbbb'] },
+ });
+ });
+
+ test('parses a body with query filter', () => {
+ const result = v.parse(batchTrashBodySchema, {
+ filter: { query: 'tag:invoice foo bar' },
+ });
+
+ expect(result).toEqual({ filter: { query: 'tag:invoice foo bar' } });
+ });
+
+ test('rejects a body without filter', () => {
+ expect(() => v.parse(batchTrashBodySchema, {})).toThrow();
+ });
+
+ test('rejects a body with both documentIds and query (strict union)', () => {
+ expect(() => v.parse(batchTrashBodySchema, {
+ filter: { documentIds: ['doc_aaaaaaaaaaaaaaaaaaaaaaaa'], query: 'foo' },
+ })).toThrow();
+ });
+
+ test('rejects an empty documentIds array', () => {
+ expect(() => v.parse(batchTrashBodySchema, {
+ filter: { documentIds: [] },
+ })).toThrow();
+ });
+
+ test(`rejects more than ${BATCH_MAX_DOCUMENTS} document ids`, () => {
+ const tooMany = Array.from({ length: BATCH_MAX_DOCUMENTS + 1 }).map((_, i) => `doc_${i.toString().padStart(24, '0')}`);
+ expect(() => v.parse(batchTrashBodySchema, {
+ filter: { documentIds: tooMany },
+ })).toThrow();
+ });
+
+ test('rejects an invalid document id', () => {
+ expect(() => v.parse(batchTrashBodySchema, {
+ filter: { documentIds: ['not-a-doc-id'] },
+ })).toThrow();
+ });
+
+ test('an empty query is allowed', () => {
+ expect(v.parse(batchTrashBodySchema, {
+ filter: { query: '' },
+ })).toEqual({ filter: { query: '' } });
+ });
+
+ test(`rejects a query longer than 1024 characters`, () => {
+ expect(() => v.parse(batchTrashBodySchema, {
+ filter: { query: 'a'.repeat(1025) },
+ })).toThrow();
+ });
+
+ test('rejects unknown top-level keys', () => {
+ expect(() => v.parse(batchTrashBodySchema, {
+ filter: { documentIds: ['doc_aaaaaaaaaaaaaaaaaaaaaaaa'] },
+ unexpected: true,
+ })).toThrow();
+ });
+ });
+});
diff --git a/apps/papra-server/src/modules/documents/documents-batch/documents-batch.schemas.ts b/apps/papra-server/src/modules/documents/documents-batch/documents-batch.schemas.ts
new file mode 100644
index 00000000..e5144157
--- /dev/null
+++ b/apps/papra-server/src/modules/documents/documents-batch/documents-batch.schemas.ts
@@ -0,0 +1,22 @@
+import * as v from 'valibot';
+import { documentIdSchema, searchDocumentsQuerySchema } from '../documents.schemas';
+import { BATCH_MAX_DOCUMENTS } from './documents-batch.constants';
+
+export const batchTargetFilterSchema = v.union([
+ v.strictObject({
+ documentIds: v.pipe(
+ v.array(documentIdSchema),
+ v.minLength(1),
+ v.maxLength(BATCH_MAX_DOCUMENTS),
+ ),
+ }),
+ v.strictObject({
+ query: searchDocumentsQuerySchema,
+ }),
+]);
+
+export const batchTrashBodySchema = v.strictObject({
+ filter: batchTargetFilterSchema,
+});
+
+export type BatchTargetFilter = v.InferOutput<typeof batchTargetFilterSchema>;
diff --git a/apps/papra-server/src/modules/documents/documents-batch/documents-batch.usecases.test.ts b/apps/papra-server/src/modules/documents/documents-batch/documents-batch.usecases.test.ts
new file mode 100644
index 00000000..f362273c
--- /dev/null
+++ b/apps/papra-server/src/modules/documents/documents-batch/documents-batch.usecases.test.ts
@@ -0,0 +1,276 @@
+import type { DocumentSearchServices } from '../document-search/document-search.types';
+import { describe, expect, test } from 'vitest';
+import { createInMemoryDatabase } from '../../app/database/database.test-utils';
+import { createTestEventServices } from '../../app/events/events.test-utils';
+import { ORGANIZATION_ROLES } from '../../organizations/organizations.constants';
+import { createDatabaseFts5DocumentSearchServices } from '../document-search/database-fts5/database-fts5.document-search-provider';
+import { createDocumentsRepository } from '../documents.repository';
+import { documentsTable } from '../documents.table';
+import { resolveBatchTargetDocumentIds, trashDocumentsBatch } from './documents-batch.usecases';
+
+function createStubSearchServices({ documentIds = [] }: { documentIds?: string[] } = {}) {
+ const calls: Parameters<DocumentSearchServices['getDocumentIdsMatchingQuery']>[0][] = [];
+
+ const services: DocumentSearchServices = {
+ name: 'stub-search-service',
+ searchDocuments: async () => ({ documents: [], documentsCount: 0 }),
+ getDocumentIdsMatchingQuery: async (args) => {
+ calls.push(args);
+ return { documentIds };
+ },
+ indexDocuments: async () => {},
+ updateDocuments: async () => {},
+ deleteDocuments: async () => {},
+ };
+
+ return { services, calls };
+}
+
+const baseDocument = {
+ organizationId: 'organization-1',
+ mimeType: 'text/plain',
+ originalStorageKey: 'organization-1/originals/document.txt',
+ originalName: 'document.txt',
+};
+
+describe('documents-batch usecases', () => {
+ describe('resolveBatchTargetDocumentIds', () => {
+ test('returns the provided documentIds without invoking the search service', async () => {
+ const { services, calls } = createStubSearchServices();
+
+ const { documentIds } = await resolveBatchTargetDocumentIds({
+ filter: { documentIds: ['doc-1', 'doc-2'] },
+ organizationId: 'organization-1',
+ documentSearchServices: services,
+ });
+
+ expect(documentIds).to.eql(['doc-1', 'doc-2']);
+ expect(calls).to.eql([]);
+ });
+
+ test('on the query path, delegates to the search service without enforcing a cap', async () => {
+ const { services, calls } = createStubSearchServices({ documentIds: ['doc-1', 'doc-2'] });
+
+ const { documentIds } = await resolveBatchTargetDocumentIds({
+ filter: { query: 'tag:invoice' },
+ organizationId: 'organization-1',
+ documentSearchServices: services,
+ });
+
+ expect(documentIds).to.eql(['doc-1', 'doc-2']);
+ expect(calls).to.eql([{
+ organizationId: 'organization-1',
+ searchQuery: 'tag:invoice',
+ }]);
+ });
+ });
+
+ describe('trashDocumentsBatch', () => {
+ test('trashes documents scoped to the organization, ignoring cross-org ids', async () => {
+ const { db } = await createInMemoryDatabase({
+ users: [{ id: 'user-1', email: '[email protected]' }],
+ organizations: [
+ { id: 'organization-1', name: 'Organization 1' },
+ { id: 'organization-2', name: 'Organization 2' },
+ ],
+ organizationMembers: [{ organizationId: 'organization-1', userId: 'user-1', role: ORGANIZATION_ROLES.OWNER }],
+ documents: [
+ { id: 'doc-1', ...baseDocument, name: 'doc 1', originalSha256Hash: 'h1' },
+ { id: 'doc-2', ...baseDocument, name: 'doc 2', originalSha256Hash: 'h2' },
+ { id: 'doc-3', organizationId: 'organization-2', mimeType: 'text/plain', originalStorageKey: 's3', originalName: 'doc 3', name: 'doc 3', originalSha256Hash: 'h3' },
+ ],
+ });
+
+ const documentsRepository = createDocumentsRepository({ db });
+ const { services } = createStubSearchServices();
+
+ const { trashedDocumentIds, trashedCount } = await trashDocumentsBatch({
+ filter: { documentIds: ['doc-1', 'doc-2', 'doc-3'] },
+ organizationId: 'organization-1',
+ userId: 'user-1',
+ documentsRepository,
+ documentSearchServices: services,
+ eventServices: createTestEventServices(),
+ });
+
+ expect(trashedDocumentIds.toSorted()).to.eql(['doc-1', 'doc-2']);
+ expect(trashedCount).to.eql(2);
+
+ const records = await db.select().from(documentsTable);
+ const byId = Object.fromEntries(records.map(r => [r.id, r]));
+ expect(byId['doc-1']?.isDeleted).to.eql(true);
+ expect(byId['doc-2']?.isDeleted).to.eql(true);
+ expect(byId['doc-3']?.isDeleted).to.eql(false);
+ });
+
+ test('does not re-trash documents that are already in the trash', async () => {
+ const { db } = await createInMemoryDatabase({
+ users: [
+ { id: 'user-1', email: '[email protected]' },
+ { id: 'user-2', email: '[email protected]' },
+ ],
+ organizations: [{ id: 'organization-1', name: 'Organization 1' }],
+ documents: [
+ { id: 'doc-1', ...baseDocument, name: 'doc 1', originalSha256Hash: 'h1', isDeleted: true, deletedBy: 'user-1', deletedAt: new Date('2026-01-01') },
+ { id: 'doc-2', ...baseDocument, name: 'doc 2', originalSha256Hash: 'h2' },
+ ],
+ });
+
+ const documentsRepository = createDocumentsRepository({ db });
+ const { services } = createStubSearchServices();
+
+ const { trashedDocumentIds } = await trashDocumentsBatch({
+ filter: { documentIds: ['doc-1', 'doc-2'] },
+ organizationId: 'organization-1',
+ userId: 'user-2',
+ documentsRepository,
+ documentSearchServices: services,
+ eventServices: createTestEventServices(),
+ });
+
+ expect(trashedDocumentIds).to.eql(['doc-2']);
+
+ const records = await db.select().from(documentsTable);
+ const byId = Object.fromEntries(records.map(r => [r.id, r]));
+ // doc-1 keeps its original deletedBy / deletedAt, untouched
+ expect(byId['doc-1']?.deletedBy).to.eql('user-1');
+ expect(byId['doc-1']?.deletedAt).to.eql(new Date('2026-01-01'));
+ expect(byId['doc-2']?.isDeleted).to.eql(true);
+ expect(byId['doc-2']?.deletedBy).to.eql('user-2');
+ });
+
+ test('emits a documents.trashed event with the actually trashed ids', async () => {
+ const { db } = await createInMemoryDatabase({
+ users: [{ id: 'user-1', email: '[email protected]' }],
+ organizations: [{ id: 'organization-1', name: 'Organization 1' }],
+ documents: [
+ { id: 'doc-1', ...baseDocument, name: 'doc 1', originalSha256Hash: 'h1' },
+ { id: 'doc-2', ...baseDocument, name: 'doc 2', originalSha256Hash: 'h2', isDeleted: true, deletedBy: 'user-1' },
+ ],
+ });
+
+ const documentsRepository = createDocumentsRepository({ db });
+ const { services } = createStubSearchServices();
+ const eventServices = createTestEventServices();
+
+ await trashDocumentsBatch({
+ filter: { documentIds: ['doc-1', 'doc-2'] },
+ organizationId: 'organization-1',
+ userId: 'user-1',
+ documentsRepository,
+ documentSearchServices: services,
+ eventServices,
+ });
+
+ expect(eventServices.getEmittedEvents()).to.eql([{
+ eventName: 'documents.trashed',
+ payload: {
+ documentIds: ['doc-1'],
+ organizationId: 'organization-1',
+ trashedBy: 'user-1',
+ },
+ }]);
+ });
+
+ test('does not emit an event when no documents were trashed', async () => {
+ const { db } = await createInMemoryDatabase({
+ users: [{ id: 'user-1', email: '[email protected]' }],
+ organizations: [{ id: 'organization-1', name: 'Organization 1' }],
+ documents: [
+ { id: 'doc-1', ...baseDocument, name: 'doc 1', originalSha256Hash: 'h1', isDeleted: true, deletedBy: 'user-1' },
+ ],
+ });
+
+ const documentsRepository = createDocumentsRepository({ db });
+ const { services } = createStubSearchServices();
+ const eventServices = createTestEventServices();
+
+ const { trashedDocumentIds } = await trashDocumentsBatch({
+ filter: { documentIds: ['doc-1'] },
+ organizationId: 'organization-1',
+ userId: 'user-1',
+ documentsRepository,
+ documentSearchServices: services,
+ eventServices,
+ });
+
+ expect(trashedDocumentIds).to.eql([]);
+ expect(eventServices.getEmittedEvents()).to.eql([]);
+ });
+
+ test('resolves a search query to the matching documents and trashes them', async () => {
+ const documents = [
+ { id: 'doc-1', organizationId: 'organization-1', mimeType: 'application/pdf', originalStorageKey: '', originalName: 'invoice-1.pdf', name: 'invoice 1', originalSha256Hash: 'h1', content: 'tax invoice', isDeleted: false },
+ { id: 'doc-2', organizationId: 'organization-1', mimeType: 'application/pdf', originalStorageKey: '', originalName: 'invoice-2.pdf', name: 'invoice 2', originalSha256Hash: 'h2', content: 'tax invoice', isDeleted: false },
+ { id: 'doc-3', organizationId: 'organization-1', mimeType: 'application/pdf', originalStorageKey: '', originalName: 'memo.pdf', name: 'memo', originalSha256Hash: 'h3', content: 'meeting memo', isDeleted: false },
+ ];
+
+ const { db } = await createInMemoryDatabase({
+ users: [{ id: 'user-1', email: '[email protected]' }],
+ organizations: [{ id: 'organization-1', name: 'Organization 1' }],
+ documents,
+ });
+
+ const documentSearchServices = createDatabaseFts5DocumentSearchServices({ db });
+ await documentSearchServices.indexDocuments({ documents });
+
+ const documentsRepository = createDocumentsRepository({ db });
+
+ const { trashedDocumentIds } = await trashDocumentsBatch({
+ filter: { query: 'invoice' },
+ organizationId: 'organization-1',
+ userId: 'user-1',
+ documentsRepository,
+ documentSearchServices,
+ eventServices: createTestEventServices(),
+ });
+
+ expect(trashedDocumentIds.toSorted()).to.eql(['doc-1', 'doc-2']);
+
+ const records = await db.select().from(documentsTable);
+ const byId = Object.fromEntries(records.map(r => [r.id, r]));
+ expect(byId['doc-1']?.isDeleted).to.eql(true);
+ expect(byId['doc-2']?.isDeleted).to.eql(true);
+ expect(byId['doc-3']?.isDeleted).to.eql(false);
+ });
+
+ test('handles a result set larger than the SQL host-parameter limit by chunking the soft-delete', async () => {
+ // Generate a fixture with more documents than fit in a single UPDATE ... WHERE id IN (...) chunk.
+ const documentCount = 1200;
+ const documents = Array.from({ length: documentCount }).map((_, i) => ({
+ id: `doc-${i.toString().padStart(4, '0')}`,
+ organizationId: 'organization-1',
+ mimeType: 'text/plain',
+ originalStorageKey: `s/${i}`,
+ originalName: `doc-${i}.txt`,
+ name: `doc ${i}`,
+ originalSha256Hash: `h${i}`,
+ isDeleted: false,
+ }));
+
+ const { db } = await createInMemoryDatabase({
+ users: [{ id: 'user-1', email: '[email protected]' }],
+ organizations: [{ id: 'organization-1', name: 'Organization 1' }],
+ documents,
+ });
+
+ const documentsRepository = createDocumentsRepository({ db });
+ const { services } = createStubSearchServices({ documentIds: documents.map(d => d.id) });
+
+ const { trashedDocumentIds, trashedCount } = await trashDocumentsBatch({
+ filter: { query: 'irrelevant' },
+ organizationId: 'organization-1',
+ userId: 'user-1',
+ documentsRepository,
+ documentSearchServices: services,
+ eventServices: createTestEventServices(),
+ });
+
+ expect(trashedCount).to.eql(documentCount);
+ expect(trashedDocumentIds).to.have.length(documentCount);
+
+ const records = await db.select().from(documentsTable);
+ expect(records.every(r => r.isDeleted === true)).to.eql(true);
+ });
+ });
+});
diff --git a/apps/papra-server/src/modules/documents/documents-batch/documents-batch.usecases.ts b/apps/papra-server/src/modules/documents/documents-batch/documents-batch.usecases.ts
new file mode 100644
index 00000000..619ea602
--- /dev/null
+++ b/apps/papra-server/src/modules/documents/documents-batch/documents-batch.usecases.ts
@@ -0,0 +1,82 @@
+import type { EventServices } from '../../app/events/events.services';
+import type { Logger } from '../../shared/logger/logger';
+import type { DocumentSearchServices } from '../document-search/document-search.types';
+import type { DocumentsRepository } from '../documents.repository';
+import type { BatchTargetFilter } from './documents-batch.schemas';
+import { createLogger } from '../../shared/logger/logger';
+
+export async function resolveBatchTargetDocumentIds({
+ filter,
+ organizationId,
+ documentSearchServices,
+ logger = createLogger({ namespace: 'documents-batch.usecases' }),
+}: {
+ filter: BatchTargetFilter;
+ organizationId: string;
+ documentSearchServices: DocumentSearchServices;
+ logger?: Logger;
+}): Promise<{ documentIds: string[] }> {
+ const startTime = Date.now();
+
+ const { documentIds, filterKind } = 'documentIds' in filter
+ ? { documentIds: filter.documentIds, filterKind: 'documentIds' as const }
+ : { ...(await documentSearchServices.getDocumentIdsMatchingQuery({ organizationId, searchQuery: filter.query })), filterKind: 'query' as const };
+
+ logger.info({
+ organizationId,
+ filterKind,
+ resolvedCount: documentIds.length,
+ durationMs: Date.now() - startTime,
+ }, 'Resolved batch target document ids');
+
+ return { documentIds };
+}
+
+export async function trashDocumentsBatch({
+ filter,
+ organizationId,
+ userId,
+ documentsRepository,
+ documentSearchServices,
+ eventServices,
+ logger = createLogger({ namespace: 'documents-batch.usecases' }),
+}: {
+ filter: BatchTargetFilter;
+ organizationId: string;
+ userId: string;
+ documentsRepository: DocumentsRepository;
+ documentSearchServices: DocumentSearchServices;
+ eventServices: EventServices;
+ logger?: Logger;
+}) {
+ const startTime = Date.now();
+
+ const { documentIds } = await resolveBatchTargetDocumentIds({ filter, organizationId, documentSearchServices, logger });
+
+ const { trashedDocumentIds } = await documentsRepository.softDeleteDocuments({
+ documentIds,
+ organizationId,
+ userId,
+ });
+
+ if (trashedDocumentIds.length > 0) {
+ eventServices.emitEvent({
+ eventName: 'documents.trashed',
+ payload: { documentIds: trashedDocumentIds, organizationId, trashedBy: userId },
+ });
+ }
+
+ logger.info({
+ organizationId,
+ userId,
+ resolvedCount: documentIds.length,
+ trashedCount: trashedDocumentIds.length,
+ skippedCount: documentIds.length - trashedDocumentIds.length,
+ durationMs: Date.now() - startTime,
+ }, 'Executed batch document trash');
+
+ return {
+ trashedDocumentIds,
+ trashedCount: trashedDocumentIds.length,
+ };
+}
diff --git a/apps/papra-server/src/modules/documents/documents.repository.ts b/apps/papra-server/src/modules/documents/documents.repository.ts
index e5f76512..4669e436 100644
--- a/apps/papra-server/src/modules/documents/documents.repository.ts
+++ b/apps/papra-server/src/modules/documents/documents.repository.ts
@@ -4,6 +4,7 @@ import { injectArguments, safely } from '@corentinth/chisels';
import { and, count, desc, eq, inArray, lt, sql } from 'drizzle-orm';
import { createIterator } from '../app/database/database.usecases';
import { createOrganizationNotFoundError } from '../organizations/organizations.errors';
+import { chunkArray } from '../shared/arrays/arrays.utils';
import { subDays } from '../shared/date';
import { isUniqueConstraintError } from '../shared/db/constraints.models';
import { withPagination } from '../shared/db/pagination';
@@ -22,6 +23,7 @@ export function createDocumentsRepository({ db }: { db: Database }) {
getOrganizationDeletedDocuments,
getDocumentById,
softDeleteDocument,
+ softDeleteDocuments,
getOrganizationDeletedDocumentsCount,
restoreDocument,
hardDeleteDocument,
@@ -157,6 +159,42 @@ async function softDeleteDocument({ documentId, organizationId, userId, db, now
);
}
+// Chunked to stay safely under SQLite's host parameter limit (default 32766)
+// when the documentIds list is large (e.g. resolved from a search query).
+const SOFT_DELETE_CHUNK_SIZE = 500;
+
+async function softDeleteDocuments({ documentIds, organizationId, userId, db, now = new Date() }: { documentIds: string[]; organizationId: string; userId: string; db: Database; now?: Date }) {
+ if (documentIds.length === 0) {
+ return { trashedDocumentIds: [] };
+ }
+
+ const trashedDocumentIds: string[] = [];
+
+ const chunks = chunkArray(documentIds, SOFT_DELETE_CHUNK_SIZE);
+
+ for (const idsChunk of chunks) {
+ const rows = await db
+ .update(documentsTable)
+ .set({
+ isDeleted: true,
+ deletedBy: userId,
+ deletedAt: now,
+ })
+ .where(
+ and(
+ inArray(documentsTable.id, idsChunk),
+ eq(documentsTable.organizationId, organizationId),
+ eq(documentsTable.isDeleted, false),
+ ),
+ )
+ .returning({ id: documentsTable.id });
+
+ trashedDocumentIds.push(...rows.map(row => row.id));
+ }
+
+ return { trashedDocumentIds };
+}
+
async function restoreDocument({ documentId, organizationId, name, userId, db }: { documentId: string; organizationId: string; name?: string; userId?: string; db: Database }) {
const [document] = await db
.update(documentsTable)
diff --git a/apps/papra-server/src/modules/documents/documents.routes.ts b/apps/papra-server/src/modules/documents/documents.routes.ts
index 33f7d4d2..697eb815 100644
--- a/apps/papra-server/src/modules/documents/documents.routes.ts
+++ b/apps/papra-server/src/modules/documents/documents.routes.ts
@@ -18,7 +18,7 @@ import { searchOrganizationDocuments } from './document-search/document-search.u
import { createDocumentIsNotDeletedError } from './documents.errors';
import { formatDocumentForApi, formatDocumentsForApi, isDocumentSizeLimitEnabled } from './documents.models';
import { createDocumentsRepository } from './documents.repository';
-import { documentIdSchema, updateDocumentBodySchema } from './documents.schemas';
+import { documentIdSchema, searchDocumentsQuerySchema, updateDocumentBodySchema } from './documents.schemas';
import { createDocumentCreationUsecase, deleteAllTrashDocuments, deleteTrashDocument, enrichAndFormatDocumentForApi, enrichAndFormatDocumentsForApi, ensureDocumentExists, getDocumentOrThrow, restoreDocument, trashDocument, updateDocument } from './documents.usecases';
export function registerDocumentsRoutes(context: RouteDefinitionContext) {
@@ -264,7 +264,7 @@ function setupGetDocumentsRoute({ app, db, documentSearchServices }: RouteDefini
})),
validateQuery(
v.strictObject({
- searchQuery: v.optional(v.string(), ''),
+ searchQuery: v.optional(searchDocumentsQuerySchema, ''),
...createQueryPaginationSchemaKeys({ maxPageSize: 100, defaultPageSize: 100 }),
}),
),
diff --git a/apps/papra-server/src/modules/documents/documents.schemas.ts b/apps/papra-server/src/modules/documents/documents.schemas.ts
index 011dcb33..9624e12a 100644
--- a/apps/papra-server/src/modules/documents/documents.schemas.ts
+++ b/apps/papra-server/src/modules/documents/documents.schemas.ts
@@ -22,3 +22,5 @@ export const stringCoercedOcrLanguagesSchema = v.pipe(
v.transform(value => value.split(',').map(lang => lang.trim())),
ocrLanguagesSchema,
);
+
+export const searchDocumentsQuerySchema = v.pipe(v.string(), v.maxLength(1024));
diff --git a/apps/papra-server/src/modules/documents/e2e/batch-trash.e2e.test.ts b/apps/papra-server/src/modules/documents/e2e/batch-trash.e2e.test.ts
new file mode 100644
index 00000000..90e2bea4
--- /dev/null
+++ b/apps/papra-server/src/modules/documents/e2e/batch-trash.e2e.test.ts
@@ -0,0 +1,123 @@
+import { getTableColumns } from 'drizzle-orm';
+import { describe, expect, test } from 'vitest';
+import { createInMemoryDatabase } from '../../app/database/database.test-utils';
+import { createServer } from '../../app/server';
+import { createTestServerDependencies } from '../../app/server.test-utils';
+import { overrideConfig } from '../../config/config.test-utils';
+import { ORGANIZATION_ROLES } from '../../organizations/organizations.constants';
+import { pick } from '../../shared/objects';
+import { createDocumentSearchRepository } from '../document-search/database-fts5/database-fts5.repository';
+import { documentsTable } from '../documents.table';
+
+const USER_ID = 'usr_111111111111111111111111';
+const ORGANIZATION_ID = 'org_222222222222222222222222';
+
+function makeDocument(props: { id: string; name: string; content?: string }) {
+ return {
+ ...props,
+ content: props.content ?? '',
+ organizationId: ORGANIZATION_ID,
+ mimeType: 'text/plain',
+ originalName: props.name,
+ createdAt: new Date('2026-01-01'),
+ updatedAt: new Date('2026-01-01'),
+ createdBy: USER_ID,
+ originalStorageKey: `documents/${props.id}`,
+ originalSha256Hash: `hash${props.id}`,
+ isDeleted: false,
+ };
+}
+
+describe('documents e2e', () => {
+ describe('batch trash', () => {
+ test('batch-trashes documents by id, leaving non-targeted documents untouched', async () => {
+ const { db } = await createInMemoryDatabase({
+ users: [{ id: USER_ID, email: '[email protected]' }],
+ organizations: [{ id: ORGANIZATION_ID, name: 'Org 1' }],
+ organizationMembers: [{ organizationId: ORGANIZATION_ID, userId: USER_ID, role: ORGANIZATION_ROLES.OWNER }],
+ documents: [
+ makeDocument({ id: 'doc_111111111111111111111111', name: 'invoice-1.txt' }),
+ makeDocument({ id: 'doc_222222222222222222222222', name: 'invoice-2.txt' }),
+ makeDocument({ id: 'doc_333333333333333333333333', name: 'memo.txt' }),
+ ],
+ });
+
+ const { app } = createServer(createTestServerDependencies({
+ db,
+ config: overrideConfig({ env: 'test' }),
+ }));
+
+ const response = await app.request(
+ `/api/organizations/${ORGANIZATION_ID}/documents/batch/trash`,
+ {
+ method: 'POST',
+ headers: { 'content-type': 'application/json' },
+ body: JSON.stringify({ filter: { documentIds: ['doc_111111111111111111111111', 'doc_222222222222222222222222'] } }),
+ },
+ { loggedInUserId: USER_ID },
+ );
+
+ expect(response.status).to.eql(204);
+
+ const records = await db
+ .select(pick(getTableColumns(documentsTable), ['id', 'isDeleted', 'deletedBy']))
+ .from(documentsTable)
+ .orderBy(documentsTable.id);
+
+ expect(
+ records,
+ ).to.eql([
+ { id: 'doc_111111111111111111111111', isDeleted: true, deletedBy: USER_ID },
+ { id: 'doc_222222222222222222222222', isDeleted: true, deletedBy: USER_ID },
+ { id: 'doc_333333333333333333333333', isDeleted: false, deletedBy: null },
+ ]);
+ });
+
+ test('batch-trashes all documents matching a search query', async () => {
+ const documents = [
+ makeDocument({ id: 'doc_111111111111111111111111', name: 'invoice-jan.txt', content: 'january invoice' }),
+ makeDocument({ id: 'doc_222222222222222222222222', name: 'invoice-feb.txt', content: 'february invoice' }),
+ makeDocument({ id: 'doc_333333333333333333333333', name: 'meeting-notes.txt', content: 'q1 planning' }),
+ ];
+
+ const { db } = await createInMemoryDatabase({
+ users: [{ id: USER_ID, email: '[email protected]' }],
+ organizations: [{ id: ORGANIZATION_ID, name: 'Org 1' }],
+ organizationMembers: [{ organizationId: ORGANIZATION_ID, userId: USER_ID, role: ORGANIZATION_ROLES.OWNER }],
+ documents,
+ });
+
+ await createDocumentSearchRepository({ db }).indexDocuments({ documents });
+
+ const { app } = createServer(createTestServerDependencies({
+ db,
+ config: overrideConfig({ env: 'test' }),
+ }));
+
+ const response = await app.request(
+ `/api/organizations/${ORGANIZATION_ID}/documents/batch/trash`,
+ {
+ method: 'POST',
+ headers: { 'content-type': 'application/json' },
+ body: JSON.stringify({ filter: { query: 'invoice' } }),
+ },
+ { loggedInUserId: USER_ID },
+ );
+
+ expect(response.status).to.eql(204);
+
+ const records = await db
+ .select(pick(getTableColumns(documentsTable), ['id', 'isDeleted', 'deletedBy']))
+ .from(documentsTable)
+ .orderBy(documentsTable.id);
+
+ expect(
+ records,
+ ).to.eql([
+ { id: 'doc_111111111111111111111111', isDeleted: true, deletedBy: USER_ID },
+ { id: 'doc_222222222222222222222222', isDeleted: true, deletedBy: USER_ID },
+ { id: 'doc_333333333333333333333333', isDeleted: false, deletedBy: null },
+ ]);
+ });
+ });
+});
diff --git a/apps/papra-server/src/modules/shared/arrays/arrays.utils.test.ts b/apps/papra-server/src/modules/shared/arrays/arrays.utils.test.ts
index 46fe121c..490eb51d 100644
--- a/apps/papra-server/src/modules/shared/arrays/arrays.utils.test.ts
+++ b/apps/papra-server/src/modules/shared/arrays/arrays.utils.test.ts
@@ -1,5 +1,5 @@
import { describe, expect, test } from 'vitest';
-import { ensureNonEmptyArray, isNonEmptyArray } from './arrays.utils';
+import { chunkArray, ensureNonEmptyArray, isNonEmptyArray } from './arrays.utils';
describe('arrays.utils', () => {
describe('ensureNonEmptyArray', () => {
@@ -27,4 +27,18 @@ describe('arrays.utils', () => {
});
});
});
+
+ describe('chunkArray', () => {
+ test('groups array elements into chunks of specified size', () => {
+ expect(chunkArray([1, 2, 3, 4, 5], 2)).toEqual([[1, 2], [3, 4], [5]]);
+ expect(chunkArray(['a', 'b', 'c', 'd'], 3)).toEqual([['a', 'b', 'c'], ['d']]);
+ expect(chunkArray(['a', 'b', 'c', 'd'], 10)).toEqual([['a', 'b', 'c', 'd']]);
+ expect(chunkArray([], 10)).toEqual([]);
+ });
+
+ test('throws an error if chunk size is less than or equal to 0', () => {
+ expect(() => chunkArray([1, 2, 3], 0)).toThrow('Chunk size must be greater than 0');
+ expect(() => chunkArray([1, 2, 3], -1)).toThrow('Chunk size must be greater than 0');
+ });
+ });
});
diff --git a/apps/papra-server/src/modules/shared/arrays/arrays.utils.ts b/apps/papra-server/src/modules/shared/arrays/arrays.utils.ts
index 58527e06..eb5e6661 100644
--- a/apps/papra-server/src/modules/shared/arrays/arrays.utils.ts
+++ b/apps/papra-server/src/modules/shared/arrays/arrays.utils.ts
@@ -12,3 +12,15 @@ export function ensureNonEmptyArray<T>(array: T[] | undefined | null): NonEmptyA
export function isNonEmptyArray<T>(array: T[] | undefined | null): array is NonEmptyArray<T> {
return !isNil(array) && array.length > 0;
}
+
+export function chunkArray<T>(array: T[], size: number): T[][] {
+ if (size <= 0) {
+ throw new Error('Chunk size must be greater than 0');
+ }
+
+ const result: T[][] = [];
+ for (let i = 0; i < array.length; i += size) {
+ result.push(array.slice(i, i + size));
+ }
+ return result;
+}
diff --git a/packages/api-sdk/src/api-client.ts b/packages/api-sdk/src/api-client.ts
index 3745c32b..9951f803 100644
--- a/packages/api-sdk/src/api-client.ts
+++ b/packages/api-sdk/src/api-client.ts
@@ -13,6 +13,7 @@ export function createClient({ apiKey, apiBaseUrl = PAPRA_API_URL }: { apiKey: s
const methods = injectArguments(
{
uploadDocument,
+ trashDocumentsBatch,
listOrganizations,
listTags,
createTag,
@@ -42,6 +43,24 @@ async function uploadDocument({
});
}
+async function trashDocumentsBatch({
+ organizationId,
+ filter,
+ apiClient,
+}: {
+ organizationId: string;
+ filter: { documentIds: string[] } | { query: string };
+ apiClient: ApiClient;
+}) {
+ return await apiClient<{ trashedDocumentIds: string[]; trashedCount: number }>(
+ `/api/organizations/${organizationId}/documents/batch/trash`,
+ {
+ method: 'POST',
+ body: { filter },
+ },
+ );
+}
+
async function listOrganizations({ apiClient }: { apiClient: ApiClient }) {
return await apiClient<{ organizations: { id: string; name: string }[] }>('/api/organizations', {
method: 'GET',