Skip to content

armgit / papra

Public Imported from GitHub
0

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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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 });
},
});
}