The minimalistic document archiving platform.
refactor(api): migrate document tag endpoints (#1568)
Corentin Thomasset59209c991faf
diff --git a/apps/papra-server/src/modules/api/api.contracts.registry.ts b/apps/papra-server/src/modules/api/api.contracts.registry.tsindex 6623bbe2..d2e5f7de 100644--- a/apps/papra-server/src/modules/api/api.contracts.registry.ts+++ b/apps/papra-server/src/modules/api/api.contracts.registry.ts@@ -1,9 +1,11 @@import { healthCheckContract, pingContract } from '../app/health-check/health-check.api.contracts';import { getCurrentUserContract, updateCurrentUserContract } from '../users/users.api.contracts';import {+ addOrganizationDocumentTagContract,createOrganizationTagContract,deleteOrganizationTagContract,getOrganizationTagsContract,+ removeOrganizationDocumentTagContract,updateOrganizationTagContract,} from '../tags/tags.api.contracts';@@ -18,4 +20,6 @@ export const apiContracts = {createOrganizationTagContract,updateOrganizationTagContract,deleteOrganizationTagContract,+ addOrganizationDocumentTagContract,+ removeOrganizationDocumentTagContract,};diff --git a/apps/papra-server/src/modules/app/server.api.routes.ts b/apps/papra-server/src/modules/app/server.api.routes.tsindex e3568934..9046cb2f 100644--- a/apps/papra-server/src/modules/app/server.api.routes.ts+++ b/apps/papra-server/src/modules/app/server.api.routes.ts@@ -36,6 +36,15 @@ export function registerApiRoutes({ app, ...deps }: RouteDefinitionContext) {});app.use('/api/*', async (context, next) => {+ // Keep the legacy static batch route ahead of the migrated :documentId/tags route.+ // Remove this bypass when the batch endpoint joins the contract router.+ if (+ context.req.method === 'POST' &&+ /^\/api\/organizations\/[^/]+\/documents\/batch\/tags$/.test(context.req.path)+ ) {+ return next();+ }+const response = await handleApiRequest({request: context.req.raw,});diff --git a/apps/papra-server/src/modules/app/server.routes.ts b/apps/papra-server/src/modules/app/server.routes.tsindex e8e75d7b..933222b5 100644--- a/apps/papra-server/src/modules/app/server.routes.ts+++ b/apps/papra-server/src/modules/app/server.routes.ts@@ -14,7 +14,6 @@ import { registerOrganizationsRoutes } from '../organizations/organizations.routimport { registerPlanEntitlementsRoutes } from '../plan-entitlements/plan-entitlements.routes';import { registerSubscriptionsRoutes } from '../subscriptions/subscriptions.routes';import { registerTaggingRulesRoutes } from '../tagging-rules/tagging-rules.routes';-import { registerTagsRoutes } from '../tags/tags.routes';import { registerWebhooksRoutes } from '../webhooks/webhooks.routes';import { registerAuthRoutes } from './auth/auth.routes';import { registerOrganizationSettingsRoutes } from '../organizations/organization-settings/organization-settings.routes';@@ -28,7 +27,6 @@ export function registerRoutes(context: RouteDefinitionContext) {registerOrganizationSettingsRoutes(context);registerDocumentsRoutes(context);registerDocumentsBatchRoutes(context);- registerTagsRoutes(context);registerDocumentViewsRoutes(context);registerTaggingRulesRoutes(context);registerApiKeysRoutes(context);diff --git a/apps/papra-server/src/modules/tags/tags.api.contracts.ts b/apps/papra-server/src/modules/tags/tags.api.contracts.tsindex 399324ee..7d70ad9e 100644--- a/apps/papra-server/src/modules/tags/tags.api.contracts.ts+++ b/apps/papra-server/src/modules/tags/tags.api.contracts.ts@@ -2,10 +2,74 @@ import * as v from 'valibot';import { defineApiContract } from '../api/api.contracts';import { isoDateStringSchema } from '../api/api.schemas';import { organizationIdSchema } from '../organizations/organization.schemas';+import { documentIdSchema } from '../documents/documents.schemas';import { tagColorSchema, tagDescriptionSchema, tagIdSchema, tagNameSchema } from './tags.schemas';import { errorResponseDefinition } from '../api/api.contracts.errors';import { tagNotFoundErrorDefinition } from './tags.errors';+const documentTagNotFoundResponse = {+ description: 'The document or tag was not found in the organization.',+ content: {+ 'application/json': {+ schema: v.object({+ error: v.object({+ code: v.picklist(['document.not_found', 'tags.not_found']),+ message: v.string(),+ }),+ }),+ },+ },+};++export const addOrganizationDocumentTagContract = defineApiContract({+ operationId: 'addOrganizationDocumentTag',+ path: '/api/organizations/:organizationId/documents/:documentId/tags',+ method: 'POST',+ request: {+ params: v.strictObject({+ organizationId: organizationIdSchema,+ documentId: documentIdSchema,+ }),+ body: {+ 'application/json': v.strictObject({+ tagId: tagIdSchema,+ }),+ },+ },+ responses: {+ 204: {+ description: 'Adds the tag to the document.',+ content: {},+ },+ 404: documentTagNotFoundResponse,+ ...errorResponseDefinition({+ statusCode: 409,+ code: 'documents.already_has_tag',+ message: 'Document already has tag',+ }),+ },+});++export const removeOrganizationDocumentTagContract = defineApiContract({+ operationId: 'removeOrganizationDocumentTag',+ path: '/api/organizations/:organizationId/documents/:documentId/tags/:tagId',+ method: 'DELETE',+ request: {+ params: v.strictObject({+ organizationId: organizationIdSchema,+ documentId: documentIdSchema,+ tagId: tagIdSchema,+ }),+ },+ responses: {+ 204: {+ description: 'Removes the tag from the document.',+ content: {},+ },+ 404: documentTagNotFoundResponse,+ },+});+export const createOrganizationTagContract = defineApiContract({operationId: 'createOrganizationTag',path: '/api/organizations/:organizationId/tags',diff --git a/apps/papra-server/src/modules/tags/tags.api.routes.ts b/apps/papra-server/src/modules/tags/tags.api.routes.tsindex cd0098a4..95c49088 100644--- a/apps/papra-server/src/modules/tags/tags.api.routes.ts+++ b/apps/papra-server/src/modules/tags/tags.api.routes.ts@@ -1,16 +1,22 @@import type { ApiDependencies } from '../app/server.types';import { defineApiRoute } from '../api/api.routes';+import { createDocumentActivityRepository } from '../documents/document-activity/document-activity.repository';+import { deferRegisterDocumentActivityLog } from '../documents/document-activity/document-activity.usecases';+import { createDocumentNotFoundError } from '../documents/documents.errors';+import { createDocumentsRepository } from '../documents/documents.repository';import { createOrganizationsRepository } from '../organizations/organizations.repository';import { ensureUserIsInOrganization } from '../organizations/organizations.usecases';import {+ addOrganizationDocumentTagContract,createOrganizationTagContract,deleteOrganizationTagContract,getOrganizationTagsContract,+ removeOrganizationDocumentTagContract,updateOrganizationTagContract,} from './tags.api.contracts';import { createTagCreationFailedError, createTagNotFoundError } from './tags.errors';import { createTagsRepository } from './tags.repository';-import { createTag } from './tags.usecases';+import { addTagToDocument, createTag } from './tags.usecases';export function buildTagsApiRoutes(deps: ApiDependencies) {return [@@ -18,9 +24,114 @@ export function buildTagsApiRoutes(deps: ApiDependencies) {setupCreateOrganizationTagRoute(deps),setupUpdateOrganizationTagRoute(deps),setupDeleteOrganizationTagRoute(deps),+ setupAddTagToDocumentRoute(deps),+ setupRemoveTagFromDocumentRoute(deps),];}+function setupAddTagToDocumentRoute({+ resolveAuthenticationContext,+ db,+ webhookTriggerServices,+}: ApiDependencies) {+ return defineApiRoute({+ contract: addOrganizationDocumentTagContract,+ resolveContext: resolveAuthenticationContext({+ apiKeyPermissions: ['documents:update', 'tags:read'],+ }),+ handler: async ({+ context: { userId },+ params: { organizationId, documentId },+ body: { tagId },+ }) => {+ const tagsRepository = createTagsRepository({ db });+ const organizationsRepository = createOrganizationsRepository({ db });+ const documentsRepository = createDocumentsRepository({ db });+ const documentActivityRepository = createDocumentActivityRepository({ db });++ await ensureUserIsInOrganization({ userId, organizationId, organizationsRepository });++ const [{ document }, { tag }] = await Promise.all([+ documentsRepository.getDocumentById({ organizationId, documentId }),+ tagsRepository.getTagById({ tagId, organizationId }),+ ]);++ if (!document) {+ throw createDocumentNotFoundError();+ }++ if (!tag) {+ throw createTagNotFoundError();+ }++ await addTagToDocument({+ tagId,+ documentId,+ organizationId,+ userId,+ tag,+ tagsRepository,+ webhookTriggerServices,+ documentActivityRepository,+ });++ return { status: 204 };+ },+ });+}++function setupRemoveTagFromDocumentRoute({+ resolveAuthenticationContext,+ db,+ webhookTriggerServices,+}: ApiDependencies) {+ return defineApiRoute({+ contract: removeOrganizationDocumentTagContract,+ resolveContext: resolveAuthenticationContext({+ apiKeyPermissions: ['documents:update', 'tags:read'],+ }),+ handler: async ({ context: { userId }, params: { organizationId, documentId, tagId } }) => {+ const tagsRepository = createTagsRepository({ db });+ const organizationsRepository = createOrganizationsRepository({ db });+ const documentActivityRepository = createDocumentActivityRepository({ db });+ const documentsRepository = createDocumentsRepository({ db });++ await ensureUserIsInOrganization({ userId, organizationId, organizationsRepository });++ const [{ document }, { tag }] = await Promise.all([+ documentsRepository.getDocumentById({ organizationId, documentId }),+ tagsRepository.getTagById({ tagId, organizationId }),+ ]);++ if (!document) {+ throw createDocumentNotFoundError();+ }++ if (!tag) {+ throw createTagNotFoundError();+ }++ await tagsRepository.removeTagFromDocument({ tagId, documentId });++ webhookTriggerServices.deferTriggerWebhooks({+ organizationId,+ event: 'document:tag:removed',+ payloads: [{ documentId, organizationId, tagId, tagName: tag.name }],+ });++ deferRegisterDocumentActivityLog({+ documentId,+ event: 'untagged',+ userId,+ documentActivityRepository,+ tagId,+ });++ return { status: 204 };+ },+ });+}+function setupCreateOrganizationTagRoute({resolveAuthenticationContext,db,diff --git a/apps/papra-server/src/modules/tags/tags.routes.ts b/apps/papra-server/src/modules/tags/tags.routes.tsdeleted file mode 100644index de85568f..00000000--- a/apps/papra-server/src/modules/tags/tags.routes.ts+++ /dev/null@@ -1,145 +0,0 @@-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 { createDocumentActivityRepository } from '../documents/document-activity/document-activity.repository';-import { deferRegisterDocumentActivityLog } from '../documents/document-activity/document-activity.usecases';-import { createDocumentNotFoundError } from '../documents/documents.errors';-import { createDocumentsRepository } from '../documents/documents.repository';-import { documentIdSchema } from '../documents/documents.schemas';-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 { createTagNotFoundError } from './tags.errors';-import { createTagsRepository } from './tags.repository';-import { tagIdSchema } from './tags.schemas';-import { addTagToDocument } from './tags.usecases';--export function registerTagsRoutes(context: RouteDefinitionContext) {- setupAddTagToDocumentRoute(context);- setupRemoveTagFromDocumentRoute(context);-}--function setupAddTagToDocumentRoute({ app, db, webhookTriggerServices }: RouteDefinitionContext) {- app.post(- '/api/organizations/:organizationId/documents/:documentId/tags',- requireAuthentication({- apiKeyPermissions: [API_KEY_PERMISSIONS.DOCUMENTS.UPDATE, API_KEY_PERMISSIONS.TAGS.READ],- }),- validateParams(- v.strictObject({- organizationId: organizationIdSchema,- documentId: documentIdSchema,- }),- ),- validateJsonBody(- v.strictObject({- tagId: tagIdSchema,- }),- ),- async (context) => {- const { userId } = getUser({ context });-- const { organizationId, documentId } = context.req.valid('param');- const { tagId } = context.req.valid('json');-- const tagsRepository = createTagsRepository({ db });- const organizationsRepository = createOrganizationsRepository({ db });- const documentsRepository = createDocumentsRepository({ db });- const documentActivityRepository = createDocumentActivityRepository({ db });-- await ensureUserIsInOrganization({ userId, organizationId, organizationsRepository });-- const [{ document }, { tag }] = await Promise.all([- documentsRepository.getDocumentById({ organizationId, documentId }),- tagsRepository.getTagById({ tagId, organizationId }),- ]);-- if (!document) {- throw createDocumentNotFoundError();- }-- if (!tag) {- throw createTagNotFoundError();- }-- await addTagToDocument({- tagId,- documentId,- organizationId,- userId,- tag,- tagsRepository,- webhookTriggerServices,- documentActivityRepository,- });-- return context.body(null, 204);- },- );-}--function setupRemoveTagFromDocumentRoute({- app,- db,- webhookTriggerServices,-}: RouteDefinitionContext) {- app.delete(- '/api/organizations/:organizationId/documents/:documentId/tags/:tagId',- requireAuthentication({- apiKeyPermissions: [API_KEY_PERMISSIONS.DOCUMENTS.UPDATE, API_KEY_PERMISSIONS.TAGS.READ],- }),- validateParams(- v.strictObject({- organizationId: organizationIdSchema,- documentId: documentIdSchema,- tagId: tagIdSchema,- }),- ),- async (context) => {- const { userId } = getUser({ context });-- const { organizationId, documentId, tagId } = context.req.valid('param');-- const tagsRepository = createTagsRepository({ db });- const organizationsRepository = createOrganizationsRepository({ db });- const documentActivityRepository = createDocumentActivityRepository({ db });- const documentsRepository = createDocumentsRepository({ db });-- await ensureUserIsInOrganization({ userId, organizationId, organizationsRepository });-- const [{ document }, { tag }] = await Promise.all([- documentsRepository.getDocumentById({ organizationId, documentId }),- tagsRepository.getTagById({ tagId, organizationId }),- ]);-- if (!document) {- throw createDocumentNotFoundError();- }-- if (!tag) {- throw createTagNotFoundError();- }-- await tagsRepository.removeTagFromDocument({ tagId, documentId });-- webhookTriggerServices.deferTriggerWebhooks({- organizationId,- event: 'document:tag:removed',- payloads: [{ documentId, organizationId, tagId, tagName: tag.name }],- });-- deferRegisterDocumentActivityLog({- documentId,- event: 'untagged',- userId,- documentActivityRepository,- tagId,- });-- return context.body(null, 204);- },- );-}