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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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; organireturn { 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 };+}