Skip to content

armgit / papra

Public Imported from GitHub
0

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.ts
index 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.ts
index 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.ts
index 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.rout
import { 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.ts
index 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.ts
index 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.ts
deleted file mode 100644
index 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);
- },
- );
-}