Skip to content

armgit / papra

Public Imported from GitHub
0

The minimalistic document archiving platform.

feat(documents-batch): add batch tagging endpoint (#1079)

Corentin Thomasset32d80b0b4b04
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
index 0842f4e1..445dd65c 100644
--- 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
@@ -1 +1,2 @@
export const BATCH_MAX_DOCUMENTS = 1000;
+export const BATCH_MAX_TAGS_PER_REQUEST = 50;
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
index bcb31f20..57ed69b8 100644
--- 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
@@ -1,17 +1,21 @@
import type { RouteDefinitionContext } from '../../app/server.types';
import * as v from 'valibot';
+import { API_KEY_PERMISSIONS } from '../../api-keys/api-keys.constants';
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 { createTagsRepository } from '../../tags/tags.repository';
+import { createDocumentActivityRepository } from '../document-activity/document-activity.repository';
import { createDocumentsRepository } from '../documents.repository';
-import { batchTrashBodySchema } from './documents-batch.schemas';
-import { trashDocumentsBatch } from './documents-batch.usecases';
+import { batchTagsBodySchema, batchTrashBodySchema } from './documents-batch.schemas';
+import { tagDocumentsBatch, trashDocumentsBatch } from './documents-batch.usecases';
export function registerDocumentsBatchRoutes(context: RouteDefinitionContext) {
setupBatchTrashDocumentsRoute(context);
+ setupBatchTagDocumentsRoute(context);
}
function setupBatchTrashDocumentsRoute({ app, db, eventServices, documentSearchServices }: RouteDefinitionContext) {
@@ -45,3 +49,41 @@ function setupBatchTrashDocumentsRoute({ app, db, eventServices, documentSearchS
},
);
}
+
+function setupBatchTagDocumentsRoute({ app, db, documentSearchServices, webhookTriggerServices }: RouteDefinitionContext) {
+ app.post(
+ '/api/organizations/:organizationId/documents/batch/tags',
+ requireAuthentication({ apiKeyPermissions: [API_KEY_PERMISSIONS.DOCUMENTS.UPDATE, API_KEY_PERMISSIONS.TAGS.READ] }),
+ validateParams(v.strictObject({
+ organizationId: organizationIdSchema,
+ })),
+ validateJsonBody(batchTagsBodySchema),
+ async (context) => {
+ const { userId } = getUser({ context });
+ const { organizationId } = context.req.valid('param');
+ const { filter, addTagIds, removeTagIds } = context.req.valid('json');
+
+ const documentsRepository = createDocumentsRepository({ db });
+ const organizationsRepository = createOrganizationsRepository({ db });
+ const tagsRepository = createTagsRepository({ db });
+ const documentActivityRepository = createDocumentActivityRepository({ db });
+
+ await ensureUserIsInOrganization({ userId, organizationId, organizationsRepository });
+
+ await tagDocumentsBatch({
+ filter,
+ addTagIds,
+ removeTagIds,
+ organizationId,
+ userId,
+ documentsRepository,
+ tagsRepository,
+ documentSearchServices,
+ webhookTriggerServices,
+ documentActivityRepository,
+ });
+
+ 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
index 54b6a007..e6316693 100644
--- 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
@@ -1,7 +1,7 @@
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';
+import { BATCH_MAX_DOCUMENTS, BATCH_MAX_TAGS_PER_REQUEST } from './documents-batch.constants';
+import { batchTagsBodySchema, batchTrashBodySchema } from './documents-batch.schemas';
describe('documents-batch.schemas', () => {
describe('batchTrashBodySchema', () => {
@@ -71,4 +71,96 @@ describe('documents-batch.schemas', () => {
})).toThrow();
});
});
+
+ describe('batchTagsBodySchema', () => {
+ const documentsFilter = { documentIds: ['doc_aaaaaaaaaaaaaaaaaaaaaaaa'] };
+
+ test('parses a body with addTagIds only', () => {
+ expect(v.parse(batchTagsBodySchema, {
+ filter: documentsFilter,
+ addTagIds: ['tag_aaaaaaaaaaaaaaaaaaaaaaaa'],
+ })).toEqual({
+ filter: documentsFilter,
+ addTagIds: ['tag_aaaaaaaaaaaaaaaaaaaaaaaa'],
+ removeTagIds: [],
+ });
+ });
+
+ test('parses a body with removeTagIds only', () => {
+ expect(v.parse(batchTagsBodySchema, {
+ filter: documentsFilter,
+ removeTagIds: ['tag_bbbbbbbbbbbbbbbbbbbbbbbb'],
+ })).toEqual({
+ filter: documentsFilter,
+ addTagIds: [],
+ removeTagIds: ['tag_bbbbbbbbbbbbbbbbbbbbbbbb'],
+ });
+ });
+
+ test('parses a body with both addTagIds and removeTagIds', () => {
+ expect(v.parse(batchTagsBodySchema, {
+ filter: documentsFilter,
+ addTagIds: ['tag_aaaaaaaaaaaaaaaaaaaaaaaa'],
+ removeTagIds: ['tag_bbbbbbbbbbbbbbbbbbbbbbbb'],
+ })).toEqual({
+ filter: documentsFilter,
+ addTagIds: ['tag_aaaaaaaaaaaaaaaaaaaaaaaa'],
+ removeTagIds: ['tag_bbbbbbbbbbbbbbbbbbbbbbbb'],
+ });
+ });
+
+ test('accepts a query filter', () => {
+ expect(v.parse(batchTagsBodySchema, {
+ filter: { query: 'invoice' },
+ addTagIds: ['tag_aaaaaaaaaaaaaaaaaaaaaaaa'],
+ })).toEqual({
+ filter: { query: 'invoice' },
+ addTagIds: ['tag_aaaaaaaaaaaaaaaaaaaaaaaa'],
+ removeTagIds: [],
+ });
+ });
+
+ test('rejects when both addTagIds and removeTagIds are omitted', () => {
+ expect(() => v.parse(batchTagsBodySchema, { filter: documentsFilter })).toThrow();
+ });
+
+ test('rejects when both addTagIds and removeTagIds are empty', () => {
+ expect(() => v.parse(batchTagsBodySchema, {
+ filter: documentsFilter,
+ addTagIds: [],
+ removeTagIds: [],
+ })).toThrow();
+ });
+
+ test('rejects when addTagIds and removeTagIds overlap', () => {
+ expect(() => v.parse(batchTagsBodySchema, {
+ filter: documentsFilter,
+ addTagIds: ['tag_aaaaaaaaaaaaaaaaaaaaaaaa'],
+ removeTagIds: ['tag_aaaaaaaaaaaaaaaaaaaaaaaa'],
+ })).toThrow();
+ });
+
+ test('rejects an invalid tag id', () => {
+ expect(() => v.parse(batchTagsBodySchema, {
+ filter: documentsFilter,
+ addTagIds: ['not-a-tag-id'],
+ })).toThrow();
+ });
+
+ test(`rejects more than ${BATCH_MAX_TAGS_PER_REQUEST} addTagIds`, () => {
+ const tooMany = Array.from({ length: BATCH_MAX_TAGS_PER_REQUEST + 1 }).map((_, i) => `tag_${i.toString().padStart(24, '0')}`);
+ expect(() => v.parse(batchTagsBodySchema, {
+ filter: documentsFilter,
+ addTagIds: tooMany,
+ })).toThrow();
+ });
+
+ test('rejects unknown top-level keys', () => {
+ expect(() => v.parse(batchTagsBodySchema, {
+ filter: documentsFilter,
+ addTagIds: ['tag_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
index e5144157..110db9ec 100644
--- 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
@@ -1,6 +1,7 @@
import * as v from 'valibot';
+import { tagIdSchema } from '../../tags/tags.schemas';
import { documentIdSchema, searchDocumentsQuerySchema } from '../documents.schemas';
-import { BATCH_MAX_DOCUMENTS } from './documents-batch.constants';
+import { BATCH_MAX_DOCUMENTS, BATCH_MAX_TAGS_PER_REQUEST } from './documents-batch.constants';
export const batchTargetFilterSchema = v.union([
v.strictObject({
@@ -19,4 +20,28 @@ export const batchTrashBodySchema = v.strictObject({
filter: batchTargetFilterSchema,
});
+const tagIdsListSchema = v.optional(
+ v.pipe(v.array(tagIdSchema), v.maxLength(BATCH_MAX_TAGS_PER_REQUEST)),
+ [],
+);
+
+export const batchTagsBodySchema = v.pipe(
+ v.strictObject({
+ filter: batchTargetFilterSchema,
+ addTagIds: tagIdsListSchema,
+ removeTagIds: tagIdsListSchema,
+ }),
+ v.check(
+ ({ addTagIds, removeTagIds }) => addTagIds.length + removeTagIds.length > 0,
+ 'At least one of addTagIds or removeTagIds must be non-empty',
+ ),
+ v.check(
+ ({ addTagIds, removeTagIds }) => {
+ const removeSet = new Set(removeTagIds);
+ return addTagIds.every(id => !removeSet.has(id));
+ },
+ 'addTagIds and removeTagIds must be disjoint',
+ ),
+);
+
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
index b53179f8..7c82be1b 100644
--- 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
@@ -1,14 +1,20 @@
+import type { WebhookPayloads } from '@papra/webhooks';
+import type { WebhookTriggerServices } from '../../webhooks/webhooks.trigger.services';
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 { pick } from '../../shared/objects';
+import { createTagsRepository } from '../../tags/tags.repository';
+import { documentsTagsTable } from '../../tags/tags.table';
+import { createDocumentActivityRepository } from '../document-activity/document-activity.repository';
+import { documentActivityLogTable } from '../document-activity/document-activity.table';
import { createDatabaseFts5DocumentSearchServices } from '../document-search/database-fts5/database-fts5.document-search-provider';
import { createDocumentsRepository } from '../documents.repository';
import { documentsTable } from '../documents.table';
import { createDocumentIdsNotFromOrganizationError } from './documents-batch.errors';
-import { resolveBatchTargetDocumentIds, trashDocumentsBatch } from './documents-batch.usecases';
+import { resolveBatchTargetDocumentIds, tagDocumentsBatch, trashDocumentsBatch } from './documents-batch.usecases';
function createStubSearchServices({ documentIds = [] }: { documentIds?: string[] } = {}) {
const calls: Parameters<DocumentSearchServices['getDocumentIdsMatchingQuery']>[0][] = [];
@@ -28,6 +34,19 @@ function createStubSearchServices({ documentIds = [] }: { documentIds?: string[]
return { services, calls };
}
+function createStubWebhookTriggerServices() {
+ const calls: Parameters<WebhookTriggerServices['deferTriggerWebhooks']>[0][] = [];
+
+ const services = {
+ triggerWebhooks: (async () => {}) as WebhookTriggerServices['triggerWebhooks'],
+ deferTriggerWebhooks: ((args: Parameters<WebhookTriggerServices['deferTriggerWebhooks']>[0]) => {
+ calls.push(args);
+ }) as WebhookTriggerServices['deferTriggerWebhooks'],
+ } as WebhookTriggerServices;
+
+ return { services, calls };
+}
+
const baseDocument = {
organizationId: 'organization-1',
mimeType: 'text/plain',
@@ -332,4 +351,322 @@ describe('documents-batch usecases', () => {
expect(records.every(r => r.isDeleted === true)).to.eql(true);
});
});
+
+ describe('tagDocumentsBatch', () => {
+ const orgTags = [
+ { id: 'tag-1', name: 'Tag One', normalizedName: 'tag one', color: '#000000', organizationId: 'organization-1' },
+ { id: 'tag-2', name: 'Tag Two', normalizedName: 'tag two', color: '#111111', organizationId: 'organization-1' },
+ ];
+
+ test('adds the tag to every resolved document', async () => {
+ const { db } = await createInMemoryDatabase({
+ users: [{ id: 'user-1', email: '[email protected]' }],
+ organizations: [{ id: 'organization-1', name: 'Organization 1' }],
+ 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' },
+ ],
+ tags: orgTags,
+ });
+
+ const { services: searchServices } = createStubSearchServices();
+ const { services: webhookServices } = createStubWebhookTriggerServices();
+
+ const { taggedCount, untaggedCount } = await tagDocumentsBatch({
+ filter: { documentIds: ['doc-1', 'doc-2'] },
+ addTagIds: ['tag-1'],
+ removeTagIds: [],
+ organizationId: 'organization-1',
+ userId: 'user-1',
+ documentsRepository: createDocumentsRepository({ db }),
+ tagsRepository: createTagsRepository({ db }),
+ documentSearchServices: searchServices,
+ webhookTriggerServices: webhookServices,
+ documentActivityRepository: createDocumentActivityRepository({ db }),
+ });
+
+ expect(taggedCount).to.eql(2);
+ expect(untaggedCount).to.eql(0);
+
+ const pairs = await db.select().from(documentsTagsTable);
+ expect(pairs.map(p => `${p.documentId}:${p.tagId}`).toSorted()).to.eql(['doc-1:tag-1', 'doc-2:tag-1']);
+ });
+
+ test('rejects the request if any documentId does not belong to the organization', 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' },
+ ],
+ documents: [
+ { id: 'doc-1', ...baseDocument, name: 'doc 1', originalSha256Hash: 'h1' },
+ { id: 'doc-foreign', organizationId: 'organization-2', mimeType: 'text/plain', originalStorageKey: 's', originalName: 'foreign', name: 'foreign', originalSha256Hash: 'hf' },
+ ],
+ tags: orgTags,
+ });
+
+ const { services: searchServices } = createStubSearchServices();
+ const { services: webhookServices } = createStubWebhookTriggerServices();
+
+ await expect(tagDocumentsBatch({
+ filter: { documentIds: ['doc-1', 'doc-foreign'] },
+ addTagIds: ['tag-1'],
+ removeTagIds: [],
+ organizationId: 'organization-1',
+ userId: 'user-1',
+ documentsRepository: createDocumentsRepository({ db }),
+ tagsRepository: createTagsRepository({ db }),
+ documentSearchServices: searchServices,
+ webhookTriggerServices: webhookServices,
+ documentActivityRepository: createDocumentActivityRepository({ db }),
+ })).rejects.toThrow(createDocumentIdsNotFromOrganizationError());
+
+ const pairs = await db.select().from(documentsTagsTable);
+ expect(pairs).to.eql([]);
+ });
+
+ test('skips pairs that already exist (idempotent re-apply)', 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' },
+ ],
+ tags: orgTags,
+ });
+ await db.insert(documentsTagsTable).values([{ documentId: 'doc-1', tagId: 'tag-1' }]);
+
+ const { services: searchServices } = createStubSearchServices();
+ const { services: webhookServices, calls: webhookCalls } = createStubWebhookTriggerServices();
+
+ const { taggedCount } = await tagDocumentsBatch({
+ filter: { documentIds: ['doc-1', 'doc-2'] },
+ addTagIds: ['tag-1'],
+ removeTagIds: [],
+ organizationId: 'organization-1',
+ userId: 'user-1',
+ documentsRepository: createDocumentsRepository({ db }),
+ tagsRepository: createTagsRepository({ db }),
+ documentSearchServices: searchServices,
+ webhookTriggerServices: webhookServices,
+ documentActivityRepository: createDocumentActivityRepository({ db }),
+ });
+
+ expect(taggedCount).to.eql(1);
+ const pairs = await db.select().from(documentsTagsTable);
+ expect(pairs.map(p => `${p.documentId}:${p.tagId}`).toSorted()).to.eql(['doc-1:tag-1', 'doc-2:tag-1']);
+ expect(webhookCalls.find(c => c.event === 'document:tag:added')?.payloads).to.have.length(1);
+ });
+
+ test('removes only existing tag pairs', 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' },
+ ],
+ tags: orgTags,
+ });
+ await db.insert(documentsTagsTable).values([
+ { documentId: 'doc-1', tagId: 'tag-1' },
+ { documentId: 'doc-2', tagId: 'tag-2' },
+ ]);
+
+ const { services: searchServices } = createStubSearchServices();
+ const { services: webhookServices } = createStubWebhookTriggerServices();
+
+ const { taggedCount, untaggedCount } = await tagDocumentsBatch({
+ filter: { documentIds: ['doc-1', 'doc-2'] },
+ addTagIds: [],
+ removeTagIds: ['tag-1'],
+ organizationId: 'organization-1',
+ userId: 'user-1',
+ documentsRepository: createDocumentsRepository({ db }),
+ tagsRepository: createTagsRepository({ db }),
+ documentSearchServices: searchServices,
+ webhookTriggerServices: webhookServices,
+ documentActivityRepository: createDocumentActivityRepository({ db }),
+ });
+
+ expect(taggedCount).to.eql(0);
+ expect(untaggedCount).to.eql(1);
+
+ const pairs = await db.select().from(documentsTagsTable);
+ expect(pairs.map(p => `${p.documentId}:${p.tagId}`).toSorted()).to.eql(['doc-2:tag-2']);
+ });
+
+ test('combined add and remove in one call', 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' },
+ ],
+ tags: orgTags,
+ });
+ await db.insert(documentsTagsTable).values([{ documentId: 'doc-1', tagId: 'tag-1' }]);
+
+ const { services: searchServices } = createStubSearchServices();
+ const { services: webhookServices } = createStubWebhookTriggerServices();
+
+ const { taggedCount, untaggedCount } = await tagDocumentsBatch({
+ filter: { documentIds: ['doc-1', 'doc-2'] },
+ addTagIds: ['tag-2'],
+ removeTagIds: ['tag-1'],
+ organizationId: 'organization-1',
+ userId: 'user-1',
+ documentsRepository: createDocumentsRepository({ db }),
+ tagsRepository: createTagsRepository({ db }),
+ documentSearchServices: searchServices,
+ webhookTriggerServices: webhookServices,
+ documentActivityRepository: createDocumentActivityRepository({ db }),
+ });
+
+ expect(taggedCount).to.eql(2);
+ expect(untaggedCount).to.eql(1);
+
+ const pairs = await db.select().from(documentsTagsTable);
+ expect(pairs.map(p => `${p.documentId}:${p.tagId}`).toSorted()).to.eql(['doc-1:tag-2', 'doc-2:tag-2']);
+ });
+
+ test('throws TagNotFoundError when a tag id does not belong to the org', 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' },
+ ],
+ documents: [{ id: 'doc-1', ...baseDocument, name: 'doc 1', originalSha256Hash: 'h1' }],
+ tags: [
+ ...orgTags,
+ { id: 'tag-other-org', name: 'Other', normalizedName: 'other', color: '#222222', organizationId: 'organization-2' },
+ ],
+ });
+
+ const { services: searchServices } = createStubSearchServices();
+ const { services: webhookServices } = createStubWebhookTriggerServices();
+
+ await expect(tagDocumentsBatch({
+ filter: { documentIds: ['doc-1'] },
+ addTagIds: ['tag-other-org'],
+ removeTagIds: [],
+ organizationId: 'organization-1',
+ userId: 'user-1',
+ documentsRepository: createDocumentsRepository({ db }),
+ tagsRepository: createTagsRepository({ db }),
+ documentSearchServices: searchServices,
+ webhookTriggerServices: webhookServices,
+ documentActivityRepository: createDocumentActivityRepository({ db }),
+ })).rejects.toThrow();
+
+ const pairs = await db.select().from(documentsTagsTable);
+ expect(pairs).to.eql([]);
+ });
+
+ test('query-filter path delegates to the search service', 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' }],
+ tags: orgTags,
+ });
+
+ const { services: searchServices, calls: searchCalls } = createStubSearchServices({ documentIds: ['doc-1'] });
+ const { services: webhookServices } = createStubWebhookTriggerServices();
+
+ const { taggedCount } = await tagDocumentsBatch({
+ filter: { query: 'tag:invoice' },
+ addTagIds: ['tag-1'],
+ removeTagIds: [],
+ organizationId: 'organization-1',
+ userId: 'user-1',
+ documentsRepository: createDocumentsRepository({ db }),
+ tagsRepository: createTagsRepository({ db }),
+ documentSearchServices: searchServices,
+ webhookTriggerServices: webhookServices,
+ documentActivityRepository: createDocumentActivityRepository({ db }),
+ });
+
+ expect(taggedCount).to.eql(1);
+ expect(searchCalls).to.eql([{ organizationId: 'organization-1', searchQuery: 'tag:invoice' }]);
+ });
+
+ test('emits batched webhook trigger calls and writes activity logs in one bulk insert', 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' },
+ ],
+ tags: orgTags,
+ });
+ await db.insert(documentsTagsTable).values([{ documentId: 'doc-1', tagId: 'tag-2' }]);
+
+ const { services: searchServices } = createStubSearchServices();
+ const { services: webhookServices, calls: webhookCalls } = createStubWebhookTriggerServices();
+
+ await tagDocumentsBatch({
+ filter: { documentIds: ['doc-1', 'doc-2'] },
+ addTagIds: ['tag-1'],
+ removeTagIds: ['tag-2'],
+ organizationId: 'organization-1',
+ userId: 'user-1',
+ documentsRepository: createDocumentsRepository({ db }),
+ tagsRepository: createTagsRepository({ db }),
+ documentSearchServices: searchServices,
+ webhookTriggerServices: webhookServices,
+ documentActivityRepository: createDocumentActivityRepository({ db }),
+ });
+
+ const addedPayloads = webhookCalls.find(c => c.event === 'document:tag:added')?.payloads as Extract<WebhookPayloads, { event: 'document:tag:added' }>['payload'][] | undefined;
+ const removedPayloads = webhookCalls.find(c => c.event === 'document:tag:removed')?.payloads as Extract<WebhookPayloads, { event: 'document:tag:removed' }>['payload'][] | undefined;
+
+ expect(addedPayloads).to.have.length(2);
+ expect(addedPayloads?.every(p => p.tagId === 'tag-1' && p.tagName === 'Tag One' && p.organizationId === 'organization-1')).to.eql(true);
+
+ expect(removedPayloads).to.eql([{ documentId: 'doc-1', organizationId: 'organization-1', tagId: 'tag-2', tagName: 'Tag Two' }]);
+
+ const activityRows = await db.select().from(documentActivityLogTable);
+ const events = activityRows.map(r => `${r.documentId}:${r.event}:${r.tagId}`).toSorted();
+ expect(events).to.eql(['doc-1:tagged:tag-1', 'doc-1:untagged:tag-2', 'doc-2:tagged:tag-1']);
+ });
+
+ test('does not emit webhooks or write activity logs when nothing changes', 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' }],
+ tags: orgTags,
+ });
+ await db.insert(documentsTagsTable).values([{ documentId: 'doc-1', tagId: 'tag-1' }]);
+
+ const { services: searchServices } = createStubSearchServices();
+ const { services: webhookServices, calls: webhookCalls } = createStubWebhookTriggerServices();
+
+ const { taggedCount, untaggedCount } = await tagDocumentsBatch({
+ filter: { documentIds: ['doc-1'] },
+ addTagIds: ['tag-1'],
+ removeTagIds: ['tag-2'],
+ organizationId: 'organization-1',
+ userId: 'user-1',
+ documentsRepository: createDocumentsRepository({ db }),
+ tagsRepository: createTagsRepository({ db }),
+ documentSearchServices: searchServices,
+ webhookTriggerServices: webhookServices,
+ documentActivityRepository: createDocumentActivityRepository({ db }),
+ });
+
+ expect(taggedCount).to.eql(0);
+ expect(untaggedCount).to.eql(0);
+ expect(webhookCalls).to.eql([]);
+ const activityRows = await db.select().from(documentActivityLogTable);
+ expect(activityRows).to.eql([]);
+ });
+ });
});
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
index c89793d5..2b995bc6 100644
--- 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
@@ -1,9 +1,14 @@
import type { EventServices } from '../../app/events/events.services';
import type { Logger } from '../../shared/logger/logger';
+import type { TagsRepository } from '../../tags/tags.repository';
+import type { WebhookTriggerServices } from '../../webhooks/webhooks.trigger.services';
+import type { DocumentActivityRepository } from '../document-activity/document-activity.repository';
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';
+import { createTagNotFoundError } from '../../tags/tags.errors';
+import { registerDocumentsActivityLog } from '../document-activity/document-activity.usecases';
import { createDocumentIdsNotFromOrganizationError } from './documents-batch.errors';
async function resolvePlainDocumentIdsBatchTargetFilter({
@@ -101,3 +106,106 @@ export async function trashDocumentsBatch({
trashedCount: trashedDocumentIds.length,
};
}
+
+export async function tagDocumentsBatch({
+ filter,
+ addTagIds,
+ removeTagIds,
+ organizationId,
+ userId,
+ documentsRepository,
+ tagsRepository,
+ documentSearchServices,
+ webhookTriggerServices,
+ documentActivityRepository,
+ logger = createLogger({ namespace: 'documents-batch.usecases' }),
+}: {
+ filter: BatchTargetFilter;
+ addTagIds: string[];
+ removeTagIds: string[];
+ organizationId: string;
+ userId: string;
+ documentsRepository: DocumentsRepository;
+ tagsRepository: TagsRepository;
+ documentSearchServices: DocumentSearchServices;
+ webhookTriggerServices: WebhookTriggerServices;
+ documentActivityRepository: DocumentActivityRepository;
+ logger?: Logger;
+}) {
+ const requestedTagIds = [...new Set([...addTagIds, ...removeTagIds])];
+ const { tags } = await tagsRepository.getTagsByIds({ tagIds: requestedTagIds, organizationId });
+
+ if (tags.length !== requestedTagIds.length) {
+ throw createTagNotFoundError();
+ }
+
+ const tagsById = new Map(tags.map(tag => [tag.id, tag]));
+
+ const { documentIds } = await resolveBatchTargetDocumentIds({ filter, organizationId, documentSearchServices, documentsRepository, logger });
+
+ if (documentIds.length === 0) {
+ logger.info({
+ organizationId,
+ userId,
+ addTagCount: addTagIds.length,
+ removeTagCount: removeTagIds.length,
+ }, 'Executed batch document tag (no target documents)');
+ return { taggedCount: 0, untaggedCount: 0, insertedPairs: [], removedPairs: [] };
+ }
+
+ const [{ insertedPairs }, { removedPairs }] = await Promise.all([
+ tagsRepository.addTagsToDocumentsBatch({ documentIds, tagIds: addTagIds }),
+ tagsRepository.removeTagsFromDocumentsBatch({ documentIds, tagIds: removeTagIds }),
+ ]);
+
+ if (insertedPairs.length > 0) {
+ webhookTriggerServices.deferTriggerWebhooks({
+ organizationId,
+ event: 'document:tag:added',
+ payloads: insertedPairs.map(({ documentId, tagId }) => ({
+ documentId,
+ organizationId,
+ tagId,
+ tagName: tagsById.get(tagId)?.name ?? '',
+ })),
+ });
+ }
+
+ if (removedPairs.length > 0) {
+ webhookTriggerServices.deferTriggerWebhooks({
+ organizationId,
+ event: 'document:tag:removed',
+ payloads: removedPairs.map(({ documentId, tagId }) => ({
+ documentId,
+ organizationId,
+ tagId,
+ tagName: tagsById.get(tagId)?.name ?? '',
+ })),
+ });
+ }
+
+ await registerDocumentsActivityLog({
+ activities: [
+ ...insertedPairs.map(({ documentId, tagId }) => ({ documentId, event: 'tagged' as const, userId, tagId })),
+ ...removedPairs.map(({ documentId, tagId }) => ({ documentId, event: 'untagged' as const, userId, tagId })),
+ ],
+ documentActivityRepository,
+ });
+
+ logger.info({
+ organizationId,
+ userId,
+ resolvedCount: documentIds.length,
+ addTagCount: addTagIds.length,
+ removeTagCount: removeTagIds.length,
+ taggedCount: insertedPairs.length,
+ untaggedCount: removedPairs.length,
+ }, 'Executed batch document tag');
+
+ return {
+ taggedCount: insertedPairs.length,
+ untaggedCount: removedPairs.length,
+ insertedPairs,
+ removedPairs,
+ };
+}
diff --git a/apps/papra-server/src/modules/documents/e2e/batch-tags.e2e.test.ts b/apps/papra-server/src/modules/documents/e2e/batch-tags.e2e.test.ts
new file mode 100644
index 00000000..a050a5c5
--- /dev/null
+++ b/apps/papra-server/src/modules/documents/e2e/batch-tags.e2e.test.ts
@@ -0,0 +1,80 @@
+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 { documentsTagsTable } from '../../tags/tags.table';
+
+const USER_ID = 'usr_111111111111111111111111';
+const ORGANIZATION_ID = 'org_222222222222222222222222';
+const DOC_1 = 'doc_111111111111111111111111';
+const DOC_2 = 'doc_222222222222222222222222';
+const TAG_ADD = 'tag_111111111111111111111111';
+const TAG_REMOVE = 'tag_222222222222222222222222';
+
+function makeDocument(props: { id: string; name: string }) {
+ return {
+ ...props,
+ organizationId: ORGANIZATION_ID,
+ mimeType: 'text/plain',
+ originalName: props.name,
+ createdBy: USER_ID,
+ originalStorageKey: `documents/${props.id}`,
+ originalSha256Hash: `hash${props.id}`,
+ isDeleted: false,
+ };
+}
+
+describe('documents e2e', () => {
+ describe('batch tags', () => {
+ test('adds and removes tags across the targeted documents in a single call', 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_1, name: 'invoice-1.txt' }),
+ makeDocument({ id: DOC_2, name: 'invoice-2.txt' }),
+ ],
+ tags: [
+ { id: TAG_ADD, name: 'Reviewed', normalizedName: 'reviewed', color: '#000000', organizationId: ORGANIZATION_ID },
+ { id: TAG_REMOVE, name: 'Pending', normalizedName: 'pending', color: '#111111', organizationId: ORGANIZATION_ID },
+ ],
+ });
+
+ await db.insert(documentsTagsTable).values([{ documentId: DOC_1, tagId: TAG_REMOVE }]);
+
+ const { app } = createServer(createTestServerDependencies({
+ db,
+ config: overrideConfig({ env: 'test' }),
+ }));
+
+ const response = await app.request(
+ `/api/organizations/${ORGANIZATION_ID}/documents/batch/tags`,
+ {
+ method: 'POST',
+ headers: { 'content-type': 'application/json' },
+ body: JSON.stringify({
+ filter: { documentIds: [DOC_1, DOC_2] },
+ addTagIds: [TAG_ADD],
+ removeTagIds: [TAG_REMOVE],
+ }),
+ },
+ { loggedInUserId: USER_ID },
+ );
+
+ expect(response.status).to.eql(204);
+
+ const pairs = await db
+ .select()
+ .from(documentsTagsTable)
+ .orderBy(documentsTagsTable.documentId, documentsTagsTable.tagId);
+
+ expect(pairs).to.eql([
+ { documentId: DOC_1, tagId: TAG_ADD },
+ { documentId: DOC_2, tagId: TAG_ADD },
+ ]);
+ });
+ });
+});
diff --git a/apps/papra-server/src/modules/tags/tags.repository.ts b/apps/papra-server/src/modules/tags/tags.repository.ts
index 3f993b9e..ae7ca812 100644
--- a/apps/papra-server/src/modules/tags/tags.repository.ts
+++ b/apps/papra-server/src/modules/tags/tags.repository.ts
@@ -3,6 +3,7 @@ import type { Tag } from './tags.types';
import { injectArguments, safely } from '@corentinth/chisels';
import { and, count, desc, eq, getTableColumns, inArray, sql } from 'drizzle-orm';
import { documentsTable } from '../documents/documents.table';
+import { chunkArray } from '../shared/arrays/arrays.utils';
import { isUniqueConstraintError } from '../shared/db/constraints.models';
import { omitUndefined } from '../shared/objects';
import { isDefined } from '../shared/utils';
@@ -18,13 +19,16 @@ export function createTagsRepository({ db }: { db: Database }) {
getOrganizationTags,
getOrganizationTagsCount,
getTagById,
+ getTagsByIds,
getTagsByDocumentIds,
createTag,
deleteTag,
updateTag,
addTagToDocument,
addTagsToDocument,
+ addTagsToDocumentsBatch,
removeTagFromDocument,
+ removeTagsFromDocumentsBatch,
removeAllTagsFromDocument,
},
{ db },
@@ -93,6 +97,24 @@ async function getTagById({ tagId, organizationId, db }: { tagId: string; organi
return { tag };
}
+async function getTagsByIds({ tagIds, organizationId, db }: { tagIds: string[]; organizationId: string; db: Database }) {
+ if (tagIds.length === 0) {
+ return { tags: [] as Tag[] };
+ }
+
+ const tags = await db
+ .select()
+ .from(tagsTable)
+ .where(
+ and(
+ inArray(tagsTable.id, tagIds),
+ eq(tagsTable.organizationId, organizationId),
+ ),
+ );
+
+ return { tags };
+}
+
async function createTag({ tag, db }: { tag: { name: string; description?: string | null; color: string; organizationId: string }; db: Database }) {
const [result, error] = await safely(
db
@@ -180,3 +202,72 @@ async function removeTagFromDocument({ tagId, documentId, db }: { tagId: string;
async function removeAllTagsFromDocument({ documentId, db }: { documentId: string; db: Database }) {
await db.delete(documentsTagsTable).where(eq(documentsTagsTable.documentId, documentId));
}
+
+// Each (documentId, tagId) row uses 2 SQLite host parameters; chunk so a single statement
+// stays well under the 32766 default host-parameter cap.
+const DOCUMENTS_TAGS_PAIR_CHUNK_SIZE = 500;
+const DOCUMENTS_TAGS_DELETE_DOC_CHUNK_SIZE = 500;
+
+async function addTagsToDocumentsBatch({
+ documentIds,
+ tagIds,
+ db,
+}: {
+ documentIds: string[];
+ tagIds: string[];
+ db: Database;
+}): Promise<{ insertedPairs: { documentId: string; tagId: string }[] }> {
+ if (documentIds.length === 0 || tagIds.length === 0) {
+ return { insertedPairs: [] };
+ }
+
+ // The max tag number per document is expected to be low (50 limited by batch api endpoint)
+ // so the cartesian product is acceptable to be stored in memory
+ const allPairs = documentIds.flatMap(documentId => tagIds.map(tagId => ({ documentId, tagId })));
+
+ const insertedPairs: { documentId: string; tagId: string }[] = [];
+
+ for (const chunk of chunkArray(allPairs, DOCUMENTS_TAGS_PAIR_CHUNK_SIZE)) {
+ const rows = await db
+ .insert(documentsTagsTable)
+ .values(chunk)
+ .onConflictDoNothing()
+ .returning({ documentId: documentsTagsTable.documentId, tagId: documentsTagsTable.tagId });
+
+ insertedPairs.push(...rows);
+ }
+
+ return { insertedPairs };
+}
+
+async function removeTagsFromDocumentsBatch({
+ documentIds,
+ tagIds,
+ db,
+}: {
+ documentIds: string[];
+ tagIds: string[];
+ db: Database;
+}): Promise<{ removedPairs: { documentId: string; tagId: string }[] }> {
+ if (documentIds.length === 0 || tagIds.length === 0) {
+ return { removedPairs: [] };
+ }
+
+ const removedPairs: { documentId: string; tagId: string }[] = [];
+
+ for (const docChunk of chunkArray(documentIds, DOCUMENTS_TAGS_DELETE_DOC_CHUNK_SIZE)) {
+ const rows = await db
+ .delete(documentsTagsTable)
+ .where(
+ and(
+ inArray(documentsTagsTable.documentId, docChunk),
+ inArray(documentsTagsTable.tagId, tagIds),
+ ),
+ )
+ .returning({ documentId: documentsTagsTable.documentId, tagId: documentsTagsTable.tagId });
+
+ removedPairs.push(...rows);
+ }
+
+ return { removedPairs };
+}