The minimalistic document archiving platform.
feat(api): add document enrichment endpoint (#1588)
Corentin Thomassetf0d1bb9528e5
diff --git a/apps/papra-server/src/modules/api/api.contracts.registry.ts b/apps/papra-server/src/modules/api/api.contracts.registry.tsindex 58fa1b1e..30edd740 100644--- a/apps/papra-server/src/modules/api/api.contracts.registry.ts+++ b/apps/papra-server/src/modules/api/api.contracts.registry.ts@@ -1,6 +1,7 @@import { adminSoftDeleteOrganizationContract } from '../admin/organizations/organizations.api.contracts';import { healthCheckContract, pingContract } from '../app/health-check/health-check.api.contracts';import { getPublicConfigContract } from '../config/config.api.contracts';+import { enrichDocumentContract } from '../document-enrichment/document-enrichment.api.contracts';import {createOrganizationContract,getDeletedOrganizationsContract,@@ -40,4 +41,5 @@ export const apiContracts = {deleteOrganizationTagContract,addOrganizationDocumentTagContract,removeOrganizationDocumentTagContract,+ enrichDocumentContract,};diff --git a/apps/papra-server/src/modules/app/server.api.routes.ts b/apps/papra-server/src/modules/app/server.api.routes.tsindex f7d2285f..d6424ce6 100644--- a/apps/papra-server/src/modules/app/server.api.routes.ts+++ b/apps/papra-server/src/modules/app/server.api.routes.ts@@ -6,6 +6,7 @@ import { buildConfigApiRoutes } from '../config/config.api.routes';import { buildOrganizationsApiRoutes } from '../organizations/organizations.api.routes';import { buildUserApiRoutes } from '../users/users.api.routes';import { buildTagsApiRoutes } from '../tags/tags.api.routes';+import { buildDocumentEnrichmentApiRoutes } from '../document-enrichment/document-enrichment.api.routes';import { buildHealthCheckApiRoutes } from './health-check/health-check.api.routes';import {buildGetApiKey,@@ -21,6 +22,7 @@ function buildApiRoutes(deps: ApiDependencies) {...buildUserApiRoutes(deps),...buildOrganizationsApiRoutes(deps),...buildTagsApiRoutes(deps),+ ...buildDocumentEnrichmentApiRoutes(deps),];}diff --git a/apps/papra-server/src/modules/document-enrichment/document-enrichment.api.contracts.ts b/apps/papra-server/src/modules/document-enrichment/document-enrichment.api.contracts.tsnew file mode 100644index 00000000..b5460d57--- /dev/null+++ b/apps/papra-server/src/modules/document-enrichment/document-enrichment.api.contracts.ts@@ -0,0 +1,42 @@+import * as v from 'valibot';+import { defineApiContract } from '../api/api.contracts';+import { errorResponseDefinition } from '../api/api.contracts.errors';+import { documentIdSchema } from '../documents/documents.schemas';+import { organizationIdSchema } from '../organizations/organization.schemas';+import {+ documentEnrichmentContentRequiredErrorDefinition,+ documentEnrichmentDisabledErrorDefinition,+} from './document-enrichment.errors';+import { enrichDocumentBodySchema } from './document-enrichment.schemas';++export const enrichDocumentContract = defineApiContract({+ operationId: 'enrichDocument',+ path: '/api/organizations/:organizationId/documents/:documentId/enrich',+ method: 'POST',+ request: {+ params: v.strictObject({+ organizationId: organizationIdSchema,+ documentId: documentIdSchema,+ }),+ body: {+ 'application/json': enrichDocumentBodySchema,+ },+ },+ responses: {+ 202: {+ description: 'Schedules enrichment using the existing extracted text without rerunning OCR.',+ content: {+ 'application/json': {+ schema: v.object({ taskId: v.string() }),+ },+ },+ },+ ...errorResponseDefinition(documentEnrichmentDisabledErrorDefinition),+ ...errorResponseDefinition(documentEnrichmentContentRequiredErrorDefinition),+ ...errorResponseDefinition({+ message: 'Document not found.',+ code: 'document.not_found',+ statusCode: 404,+ }),+ },+});diff --git a/apps/papra-server/src/modules/document-enrichment/document-enrichment.api.routes.ts b/apps/papra-server/src/modules/document-enrichment/document-enrichment.api.routes.tsnew file mode 100644index 00000000..1d3f2857--- /dev/null+++ b/apps/papra-server/src/modules/document-enrichment/document-enrichment.api.routes.ts@@ -0,0 +1,55 @@+import { defineApiRoute } from '../api/api.routes';+import type { ApiDependencies } from '../app/server.types';+import { createDocumentsRepository } from '../documents/documents.repository';+import { createOrganizationSettingsRepository } from '../organizations/organization-settings/organization-settings.repository';+import { createResolveOrganizationSettingsUsecase } from '../organizations/organization-settings/organization-settings.usecases';+import { createOrganizationsRepository } from '../organizations/organizations.repository';+import { ensureUserIsInOrganization } from '../organizations/organizations.usecases';+import { enrichDocumentContract } from './document-enrichment.api.contracts';+import { buildScheduleDocumentEnrichment } from './document-enrichment.usecases';++export function buildDocumentEnrichmentApiRoutes(deps: ApiDependencies) {+ return [setupEnrichDocumentRoute(deps)];+}++export function setupEnrichDocumentRoute({+ resolveAuthenticationContext,+ db,+ config,+ taskServices,+}: ApiDependencies) {+ const organizationsRepository = createOrganizationsRepository({ db });+ const scheduleDocumentEnrichment = buildScheduleDocumentEnrichment({+ config,+ taskServices,+ documentsRepository: createDocumentsRepository({ db }),+ resolveOrganizationSettings: createResolveOrganizationSettingsUsecase({+ config,+ organizationSettingsRepository: createOrganizationSettingsRepository({ db }),+ }),+ });++ return defineApiRoute({+ contract: enrichDocumentContract,+ resolveContext: resolveAuthenticationContext({ apiKeyPermissions: ['documents:update'] }),+ handler: async ({+ context: { userId },+ params: { organizationId, documentId },+ body: { capabilities },+ }) => {+ await ensureUserIsInOrganization({ userId, organizationId, organizationsRepository });++ const { taskId } = await scheduleDocumentEnrichment({+ organizationId,+ documentId,+ capabilities,+ });++ return {+ status: 202,+ contentType: 'application/json',+ body: { taskId },+ };+ },+ });+}diff --git a/apps/papra-server/src/modules/document-enrichment/document-enrichment.errors.ts b/apps/papra-server/src/modules/document-enrichment/document-enrichment.errors.tsnew file mode 100644index 00000000..bc5a4c7b--- /dev/null+++ b/apps/papra-server/src/modules/document-enrichment/document-enrichment.errors.ts@@ -0,0 +1,21 @@+import { createErrorFactory } from '../shared/errors/errors';++export const documentEnrichmentDisabledErrorDefinition = {+ message: 'The requested document enrichment capability is disabled.',+ code: 'document_enrichment.disabled',+ statusCode: 403,+} as const;++export const createDocumentEnrichmentDisabledError = createErrorFactory(+ documentEnrichmentDisabledErrorDefinition,+);++export const documentEnrichmentContentRequiredErrorDefinition = {+ message: 'Document enrichment requires extracted text.',+ code: 'document_enrichment.content_required',+ statusCode: 400,+} as const;++export const createDocumentEnrichmentContentRequiredError = createErrorFactory(+ documentEnrichmentContentRequiredErrorDefinition,+);diff --git a/apps/papra-server/src/modules/document-enrichment/document-enrichment.schemas.ts b/apps/papra-server/src/modules/document-enrichment/document-enrichment.schemas.tsnew file mode 100644index 00000000..1d521a41--- /dev/null+++ b/apps/papra-server/src/modules/document-enrichment/document-enrichment.schemas.ts@@ -0,0 +1,9 @@+import * as v from 'valibot';++export const documentEnrichmentCapabilitySchema = v.picklist(['auto-tagging']);++export type DocumentEnrichmentCapability = v.InferOutput<typeof documentEnrichmentCapabilitySchema>;++export const enrichDocumentBodySchema = v.strictObject({+ capabilities: v.pipe(v.array(documentEnrichmentCapabilitySchema), v.minLength(1)),+});diff --git a/apps/papra-server/src/modules/document-enrichment/document-enrichment.usecases.ts b/apps/papra-server/src/modules/document-enrichment/document-enrichment.usecases.tsindex e4e4e102..13b52209 100644--- a/apps/papra-server/src/modules/document-enrichment/document-enrichment.usecases.ts+++ b/apps/papra-server/src/modules/document-enrichment/document-enrichment.usecases.ts@@ -9,6 +9,63 @@ import type { DocumentsRepository } from '../documents/documents.repository';import type { ResolveOrganizationSettingsUsecase } from '../organizations/organization-settings/organization-settings.usecases';import { createLogger } from '../shared/logger/logger';import type { TagsRepository } from '../tags/tags.repository';+import type { Config } from '../config/config.types';+import type { TaskServices } from '../tasks/tasks.services';+import type { DocumentEnrichmentCapability } from './document-enrichment.schemas';+import {+ createDocumentEnrichmentContentRequiredError,+ createDocumentEnrichmentDisabledError,+} from './document-enrichment.errors';++export function buildScheduleDocumentEnrichment({+ config,+ documentsRepository,+ resolveOrganizationSettings,+ taskServices,+}: {+ config: Pick<Config, 'ai' | 'autoTagging'>;+ documentsRepository: Pick<DocumentsRepository, 'getDocumentById'>;+ resolveOrganizationSettings: ResolveOrganizationSettingsUsecase;+ taskServices: Pick<TaskServices, 'scheduleJob'>;+}) {+ return async ({+ documentId,+ organizationId,+ capabilities,+ }: {+ documentId: string;+ organizationId: string;+ capabilities: DocumentEnrichmentCapability[];+ }) => {+ if (!config.ai.isEnabled || !config.autoTagging.isEnabled) {+ throw createDocumentEnrichmentDisabledError();+ }++ const [{ document }, { organizationSettings }] = await Promise.all([+ documentsRepository.getDocumentById({ documentId, organizationId }),+ resolveOrganizationSettings({ organizationId }),+ ]);++ if (!document || document.isDeleted) {+ throw createDocumentNotFoundError();+ }++ if (capabilities.includes('auto-tagging') && !organizationSettings.ai.autoTagging.isEnabled) {+ throw createDocumentEnrichmentDisabledError();+ }++ if (document.content.trim().length === 0) {+ throw createDocumentEnrichmentContentRequiredError();+ }++ const { jobId: taskId } = await taskServices.scheduleJob({+ taskName: 'enrich-document',+ data: { documentId, organizationId, capabilities },+ });++ return { taskId };+ };+}export function buildEnrichDocument({promptForAutoTagging,@@ -25,7 +82,20 @@ export function buildEnrichDocument({resolveOrganizationSettings: ResolveOrganizationSettingsUsecase;logger?: Logger;}) {- return async ({ documentId, organizationId }: { documentId: string; organizationId: string }) => {+ return async ({+ documentId,+ organizationId,+ capabilities = ['auto-tagging'],+ }: {+ documentId: string;+ organizationId: string;+ capabilities?: DocumentEnrichmentCapability[];+ }) => {+ // Automatic and previously queued jobs without a selection retain auto-tagging.+ if (!capabilities.includes('auto-tagging')) {+ return;+ }+const [{ document }, { tags: existingTags }, { organizationSettings }] = await Promise.all([documentsRepository.getDocumentById({ documentId, organizationId }),tagsRepository.getOrganizationTags({ organizationId }),@@ -55,7 +125,7 @@ export function buildEnrichDocument({return;}- if (!document) {+ if (!document || document.isDeleted) {throw createDocumentNotFoundError();}diff --git a/apps/papra-server/src/modules/document-enrichment/tasks/enrich-document.task.test.ts b/apps/papra-server/src/modules/document-enrichment/tasks/enrich-document.task.test.tsindex a799119d..76c1d79e 100644--- a/apps/papra-server/src/modules/document-enrichment/tasks/enrich-document.task.test.ts+++ b/apps/papra-server/src/modules/document-enrichment/tasks/enrich-document.task.test.ts@@ -132,6 +132,20 @@ describe('document enrichment task', () => {expect(await deps.db.select().from(documentsTagsTable)).toEqual([]);});+ test('a job that does not select auto-tagging does not run it even when enabled', async () => {+ const deps = await createTestDeps();+ await deps.organizationSettingsRepository.createOrUpdateOrganizationSettings({+ organizationId: 'org_1',+ settings: { aiAutoTaggingEnabled: true },+ });+ const { taskDefinition } = deps.taskRegistry.getTaskOrThrow({ taskName: 'enrich-document' });++ await taskDefinition.handler({ data: { ...documentIds, capabilities: [] }, context });++ expect(deps.generateStructuredData).not.toHaveBeenCalled();+ expect(await deps.db.select().from(documentsTagsTable)).toEqual([]);+ });+test('disabling AI prevents enrichment registration and scheduling without preventing text extraction', async () => {const deps = await createTestDeps({ aiEnabled: false });diff --git a/apps/papra-server/src/modules/document-enrichment/tasks/enrich-document.task.ts b/apps/papra-server/src/modules/document-enrichment/tasks/enrich-document.task.tsindex 7ca4f2b7..97cfc592 100644--- a/apps/papra-server/src/modules/document-enrichment/tasks/enrich-document.task.ts+++ b/apps/papra-server/src/modules/document-enrichment/tasks/enrich-document.task.ts@@ -14,6 +14,7 @@ import { createDocumentsRepository } from '../../documents/documents.repository'import type { EventServices } from '../../app/events/events.services';import type { AiServices } from '../../ai/ai.services';import { buildEnrichDocument } from '../document-enrichment.usecases';+import type { DocumentEnrichmentCapability } from '../document-enrichment.schemas';export async function registerEnrichDocumentTask({taskServices,@@ -42,9 +43,10 @@ export async function registerEnrichDocumentTask({const organizationSettingsRepository = createOrganizationSettingsRepository({ db });// TODO: remove type cast- const { documentId, organizationId } = data as {+ const { documentId, organizationId, capabilities } = data as {documentId: string;organizationId: string;+ capabilities?: DocumentEnrichmentCapability[];};const logger = createLogger({ namespace: 'documentEnrichment' });@@ -64,7 +66,7 @@ export async function registerEnrichDocumentTask({}),});- await enrichDocument({ documentId, organizationId });+ await enrichDocument({ documentId, organizationId, capabilities });},});}