From 637affecb8565975ec6d5118f3be8016256b97ca Mon Sep 17 00:00:00 2001
From: CREDO23 <bakerathierry@gmail.com>
Date: Tue, 2 Jun 2026 16:10:50 +0200
Subject: [PATCH] feat(web): add document files contract and api method

---
 .../contracts/types/document.types.ts         | 20 +++++++++++++++++++
 .../lib/apis/documents-api.service.ts         | 10 ++++++++++
 2 files changed, 30 insertions(+)

diff --git a/surfsense_web/contracts/types/document.types.ts b/surfsense_web/contracts/types/document.types.ts
index 82c6cbdaf..1d08d77cd 100644
--- a/surfsense_web/contracts/types/document.types.ts
+++ b/surfsense_web/contracts/types/document.types.ts
@@ -281,6 +281,23 @@ export const deleteDocumentResponse = z.object({
 	message: z.literal("Document deleted successfully"),
 });
 
+/**
+ * Document files (stored originals / derived artifacts)
+ */
+export const documentFileKindEnum = z.enum(["ORIGINAL", "REDACTED", "FILLED_FORM"]);
+
+export const documentFileRead = z.object({
+	id: z.number(),
+	document_id: z.number(),
+	kind: documentFileKindEnum,
+	original_filename: z.string(),
+	mime_type: z.string().nullable().optional(),
+	size_bytes: z.number(),
+	created_at: z.string(),
+});
+
+export const getDocumentFilesResponse = z.array(documentFileRead);
+
 export type Document = z.infer<typeof document>;
 export type DocumentTitleRead = z.infer<typeof documentTitleRead>;
 export type GetDocumentsRequest = z.infer<typeof getDocumentsRequest>;
@@ -314,3 +331,6 @@ export type GetDocumentChunksRequest = z.infer<typeof getDocumentChunksRequest>;
 export type GetDocumentChunksResponse = z.infer<typeof getDocumentChunksResponse>;
 export type ChunkRead = z.infer<typeof chunkRead>;
 export type ProcessingMode = z.infer<typeof processingModeEnum>;
+export type DocumentFileKind = z.infer<typeof documentFileKindEnum>;
+export type DocumentFileRead = z.infer<typeof documentFileRead>;
+export type GetDocumentFilesResponse = z.infer<typeof getDocumentFilesResponse>;
diff --git a/surfsense_web/lib/apis/documents-api.service.ts b/surfsense_web/lib/apis/documents-api.service.ts
index f9785c8a8..30a36af3c 100644
--- a/surfsense_web/lib/apis/documents-api.service.ts
+++ b/surfsense_web/lib/apis/documents-api.service.ts
@@ -30,6 +30,8 @@ import {
 	searchDocumentsResponse,
 	searchDocumentTitlesRequest,
 	searchDocumentTitlesResponse,
+	type DocumentFileRead,
+	getDocumentFilesResponse,
 	type UpdateDocumentRequest,
 	type UploadDocumentRequest,
 	updateDocumentRequest,
@@ -381,6 +383,14 @@ class DocumentsApiService {
 		});
 	};
 
+	/**
+	 * List the stored files for a document (e.g. its original upload).
+	 * Used to gate the "Download original" affordance.
+	 */
+	getDocumentFiles = async (documentId: number): Promise<DocumentFileRead[]> => {
+		return baseApiService.get(`/api/v1/documents/${documentId}/files`, getDocumentFilesResponse);
+	};
+
 	listDocumentVersions = async (documentId: number) => {
 		return baseApiService.get(`/api/v1/documents/${documentId}/versions`);
 	};