@striae-org/striae 4.2.0 → 4.3.0

package/app/utils/data/operations/confirmation-summary-operations.ts

@@ -0,0 +1,301 @@
+import type { User } from 'firebase/auth';
+import type { AnnotationData } from '~/types';
+
+import { fetchDataApi } from '../../api';
+import { canAccessCase, validateUserSession } from '../permissions';
+import {
+  DEFAULT_CONFIRMATION_SUMMARY_MAX_AGE_MS,
+  buildConfirmationSummaryPath,
+  computeCaseConfirmationAggregate,
+  getIsoNow,
+  isStaleTimestamp,
+  normalizeConfirmationSummaryDocument,
+  toFileConfirmationSummary,
+  trackCaseHit,
+  trackCaseMiss,
+  trackEnsureCall,
+  trackForceRefreshCall,
+  trackMissingFileRefresh,
+  trackRefreshedFileEntry,
+  trackRemovedFileEntry,
+  trackStaleCaseRefresh,
+  trackStaleFileRefresh,
+  trackSummaryWrite,
+  type CaseConfirmationSummary,
+  type ConfirmationSummaryEnsureOptions,
+  type FileConfirmationSummary,
+  type UserConfirmationSummaryDocument
+} from '../confirmation-summary/summary-core';
+
+async function saveConfirmationSummaryDocument(
+  user: User,
+  summary: UserConfirmationSummaryDocument
+): Promise<void> {
+  const response = await fetchDataApi(user, buildConfirmationSummaryPath(user), {
+    method: 'PUT',
+    headers: {
+      'Content-Type': 'application/json'
+    },
+    body: JSON.stringify(summary)
+  });
+
+  if (!response.ok) {
+    throw new Error(`Failed to save confirmation summary: ${response.status} ${response.statusText}`);
+  }
+}
+
+async function getFileAnnotationsForSummary(
+  user: User,
+  caseNumber: string,
+  fileId: string
+): Promise<AnnotationData | null> {
+  try {
+    const response = await fetchDataApi(
+      user,
+      `/${encodeURIComponent(user.uid)}/${encodeURIComponent(caseNumber)}/${encodeURIComponent(fileId)}/data.json`,
+      {
+        method: 'GET'
+      }
+    );
+
+    if (response.status === 404) {
+      return null;
+    }
+
+    if (!response.ok) {
+      throw new Error(`Failed to fetch file annotations: ${response.status} ${response.statusText}`);
+    }
+
+    return await response.json() as AnnotationData;
+  } catch (error) {
+    console.error(`Error fetching annotations for ${caseNumber}/${fileId}:`, error);
+    return null;
+  }
+}
+
+export const getConfirmationSummaryDocument = async (
+  user: User
+): Promise<UserConfirmationSummaryDocument> => {
+  const sessionValidation = await validateUserSession(user);
+  if (!sessionValidation.valid) {
+    throw new Error(`Session validation failed: ${sessionValidation.reason}`);
+  }
+
+  const response = await fetchDataApi(user, buildConfirmationSummaryPath(user), {
+    method: 'GET'
+  });
+
+  if (!response.ok) {
+    throw new Error(`Failed to fetch confirmation summary: ${response.status} ${response.statusText}`);
+  }
+
+  const payload = await response.json().catch(() => null) as unknown;
+  return normalizeConfirmationSummaryDocument(payload);
+};
+
+export const getCaseConfirmationSummary = async (
+  user: User,
+  caseNumber: string
+): Promise<CaseConfirmationSummary | null> => {
+  const summary = await getConfirmationSummaryDocument(user);
+  return summary.cases[caseNumber] ?? null;
+};
+
+export const ensureCaseConfirmationSummary = async (
+  user: User,
+  caseNumber: string,
+  files: Array<{ id: string }>,
+  options: ConfirmationSummaryEnsureOptions = {}
+): Promise<CaseConfirmationSummary> => {
+  trackEnsureCall();
+
+  const sessionValidation = await validateUserSession(user);
+  if (!sessionValidation.valid) {
+    throw new Error(`Session validation failed: ${sessionValidation.reason}`);
+  }
+
+  const accessCheck = await canAccessCase(user, caseNumber);
+  if (!accessCheck.allowed) {
+    throw new Error(`Access denied: ${accessCheck.reason}`);
+  }
+
+  const summary = await getConfirmationSummaryDocument(user);
+  const existingCase = summary.cases[caseNumber];
+  const filesById: Record<string, FileConfirmationSummary> = existingCase ? { ...existingCase.filesById } : {};
+  const fileIds = new Set(files.map((file) => file.id));
+  const maxAgeMs =
+    typeof options.maxAgeMs === 'number' && Number.isFinite(options.maxAgeMs) && options.maxAgeMs > 0
+      ? options.maxAgeMs
+      : DEFAULT_CONFIRMATION_SUMMARY_MAX_AGE_MS;
+  const caseIsStale =
+    options.forceRefresh === true ||
+    !existingCase ||
+    isStaleTimestamp(existingCase.updatedAt, maxAgeMs);
+
+  if (!existingCase) {
+    trackCaseMiss();
+  } else {
+    trackCaseHit();
+  }
+
+  if (options.forceRefresh === true) {
+    trackForceRefreshCall();
+  }
+
+  if (caseIsStale) {
+    trackStaleCaseRefresh();
+  }
+
+  let changed = !existingCase;
+
+  for (const fileId of Object.keys(filesById)) {
+    if (!fileIds.has(fileId)) {
+      delete filesById[fileId];
+      trackRemovedFileEntry();
+      changed = true;
+    }
+  }
+
+  const filesToRefresh = files
+    .map((file) => {
+      const existingFileSummary = filesById[file.id];
+      if (!existingFileSummary) {
+        return {
+          fileId: file.id,
+          reason: 'missing' as const
+        };
+      }
+
+      if (caseIsStale) {
+        return {
+          fileId: file.id,
+          reason: 'stale' as const
+        };
+      }
+
+      if (isStaleTimestamp(existingFileSummary.updatedAt, maxAgeMs)) {
+        return {
+          fileId: file.id,
+          reason: 'stale' as const
+        };
+      }
+
+      return null;
+    })
+    .filter((entry): entry is { fileId: string; reason: 'missing' | 'stale' } => entry !== null);
+
+  for (const entry of filesToRefresh) {
+    if (entry.reason === 'missing') {
+      trackMissingFileRefresh();
+    } else {
+      trackStaleFileRefresh();
+    }
+  }
+
+  if (filesToRefresh.length > 0) {
+    const refreshedFiles = await Promise.all(
+      filesToRefresh.map(async (entry) => {
+        const annotations = await getFileAnnotationsForSummary(user, caseNumber, entry.fileId);
+        return {
+          fileId: entry.fileId,
+          summary: toFileConfirmationSummary(annotations)
+        };
+      })
+    );
+
+    for (const refreshedFile of refreshedFiles) {
+      filesById[refreshedFile.fileId] = refreshedFile.summary;
+      trackRefreshedFileEntry();
+      changed = true;
+    }
+  }
+
+  const aggregate = computeCaseConfirmationAggregate(filesById);
+  const updatedCaseSummary: CaseConfirmationSummary = {
+    includeConfirmation: aggregate.includeConfirmation,
+    isConfirmed: aggregate.isConfirmed,
+    updatedAt: getIsoNow(),
+    filesById
+  };
+
+  const aggregateChanged =
+    !existingCase ||
+    existingCase.includeConfirmation !== updatedCaseSummary.includeConfirmation ||
+    existingCase.isConfirmed !== updatedCaseSummary.isConfirmed;
+
+  if (changed || aggregateChanged || caseIsStale) {
+    summary.updatedAt = getIsoNow();
+    summary.cases[caseNumber] = updatedCaseSummary;
+    await saveConfirmationSummaryDocument(user, summary);
+    trackSummaryWrite();
+    return updatedCaseSummary;
+  }
+
+  return existingCase as CaseConfirmationSummary;
+};
+
+export const upsertFileConfirmationSummary = async (
+  user: User,
+  caseNumber: string,
+  fileId: string,
+  annotationData: AnnotationData | null
+): Promise<void> => {
+  const summary = await getConfirmationSummaryDocument(user);
+  const caseSummary = summary.cases[caseNumber] ?? {
+    includeConfirmation: false,
+    isConfirmed: false,
+    updatedAt: getIsoNow(),
+    filesById: {}
+  };
+
+  caseSummary.filesById[fileId] = toFileConfirmationSummary(annotationData);
+
+  const aggregate = computeCaseConfirmationAggregate(caseSummary.filesById);
+  caseSummary.includeConfirmation = aggregate.includeConfirmation;
+  caseSummary.isConfirmed = aggregate.isConfirmed;
+  caseSummary.updatedAt = getIsoNow();
+
+  summary.cases[caseNumber] = caseSummary;
+  summary.updatedAt = getIsoNow();
+
+  await saveConfirmationSummaryDocument(user, summary);
+};
+
+export const removeFileConfirmationSummary = async (
+  user: User,
+  caseNumber: string,
+  fileId: string
+): Promise<void> => {
+  const summary = await getConfirmationSummaryDocument(user);
+  const caseSummary = summary.cases[caseNumber];
+  if (!caseSummary || !caseSummary.filesById[fileId]) {
+    return;
+  }
+
+  delete caseSummary.filesById[fileId];
+
+  const aggregate = computeCaseConfirmationAggregate(caseSummary.filesById);
+  caseSummary.includeConfirmation = aggregate.includeConfirmation;
+  caseSummary.isConfirmed = aggregate.isConfirmed;
+  caseSummary.updatedAt = getIsoNow();
+
+  summary.cases[caseNumber] = caseSummary;
+  summary.updatedAt = getIsoNow();
+
+  await saveConfirmationSummaryDocument(user, summary);
+};
+
+export const removeCaseConfirmationSummary = async (
+  user: User,
+  caseNumber: string
+): Promise<void> => {
+  const summary = await getConfirmationSummaryDocument(user);
+  if (!summary.cases[caseNumber]) {
+    return;
+  }
+
+  delete summary.cases[caseNumber];
+  summary.updatedAt = getIsoNow();
+
+  await saveConfirmationSummaryDocument(user, summary);
+};

package/app/utils/data/operations/file-annotation-operations.ts

@@ -0,0 +1,196 @@
+import type { User } from 'firebase/auth';
+import type { AnnotationData } from '~/types';
+
+import { fetchDataApi } from '../../api';
+import { canAccessCase, canModifyCase, validateUserSession } from '../permissions';
+import { removeFileConfirmationSummary, upsertFileConfirmationSummary } from './confirmation-summary-operations';
+import type { DataOperationOptions } from './types';
+
+/**
+ * Get file annotation data from R2 storage.
+ */
+export const getFileAnnotations = async (
+  user: User,
+  caseNumber: string,
+  fileId: string
+): Promise<AnnotationData | null> => {
+  try {
+    const sessionValidation = await validateUserSession(user);
+    if (!sessionValidation.valid) {
+      throw new Error(`Session validation failed: ${sessionValidation.reason}`);
+    }
+
+    const accessCheck = await canAccessCase(user, caseNumber);
+    if (!accessCheck.allowed) {
+      throw new Error(`Access denied: ${accessCheck.reason}`);
+    }
+
+    if (!fileId || typeof fileId !== 'string') {
+      throw new Error('Invalid file ID provided');
+    }
+
+    const response = await fetchDataApi(
+      user,
+      `/${encodeURIComponent(user.uid)}/${encodeURIComponent(caseNumber)}/${encodeURIComponent(fileId)}/data.json`,
+      {
+        method: 'GET'
+      }
+    );
+
+    if (response.status === 404) {
+      return null;
+    }
+
+    if (!response.ok) {
+      throw new Error(`Failed to fetch file annotations: ${response.status} ${response.statusText}`);
+    }
+
+    return await response.json() as AnnotationData;
+  } catch (error) {
+    console.error(`Error fetching annotations for ${caseNumber}/${fileId}:`, error);
+    return null;
+  }
+};
+
+/**
+ * Save file annotation data to R2 storage.
+ */
+export const saveFileAnnotations = async (
+  user: User,
+  caseNumber: string,
+  fileId: string,
+  annotationData: AnnotationData,
+  options: DataOperationOptions = {}
+): Promise<void> => {
+  try {
+    const sessionValidation = await validateUserSession(user);
+    if (!sessionValidation.valid) {
+      throw new Error(`Session validation failed: ${sessionValidation.reason}`);
+    }
+
+    if (options.skipValidation !== true) {
+      const modifyCheck = await canModifyCase(user, caseNumber);
+      if (!modifyCheck.allowed) {
+        throw new Error(`Modification denied: ${modifyCheck.reason}`);
+      }
+    }
+
+    if (!fileId || typeof fileId !== 'string') {
+      throw new Error('Invalid file ID provided');
+    }
+
+    if (!annotationData || typeof annotationData !== 'object') {
+      throw new Error('Invalid annotation data provided');
+    }
+
+    // Enforce immutability once confirmation data exists on an image.
+    const existingResponse = await fetchDataApi(
+      user,
+      `/${encodeURIComponent(user.uid)}/${encodeURIComponent(caseNumber)}/${encodeURIComponent(fileId)}/data.json`,
+      {
+        method: 'GET'
+      }
+    );
+
+    if (existingResponse.ok) {
+      const existingAnnotations = await existingResponse.json() as AnnotationData;
+      if (existingAnnotations?.confirmationData) {
+        throw new Error('Cannot modify annotations for a confirmed image');
+      }
+    } else if (existingResponse.status !== 404) {
+      throw new Error(`Failed to verify existing annotations: ${existingResponse.status} ${existingResponse.statusText}`);
+    }
+
+    const dataToSave = {
+      ...annotationData,
+      updatedAt: new Date().toISOString()
+    };
+
+    const response = await fetchDataApi(
+      user,
+      `/${encodeURIComponent(user.uid)}/${encodeURIComponent(caseNumber)}/${encodeURIComponent(fileId)}/data.json`,
+      {
+        method: 'PUT',
+        headers: {
+          'Content-Type': 'application/json'
+        },
+        body: JSON.stringify(dataToSave)
+      }
+    );
+
+    if (!response.ok) {
+      throw new Error(`Failed to save file annotations: ${response.status} ${response.statusText}`);
+    }
+
+    try {
+      await upsertFileConfirmationSummary(user, caseNumber, fileId, dataToSave);
+    } catch (summaryError) {
+      console.warn(`Failed to update confirmation summary for ${caseNumber}/${fileId}:`, summaryError);
+    }
+  } catch (error) {
+    console.error(`Error saving annotations for ${caseNumber}/${fileId}:`, error);
+    throw error;
+  }
+};
+
+/**
+ * Delete file annotation data from R2 storage.
+ */
+export const deleteFileAnnotations = async (
+  user: User,
+  caseNumber: string,
+  fileId: string,
+  options: { skipValidation?: boolean } = {}
+): Promise<void> => {
+  try {
+    const sessionValidation = await validateUserSession(user);
+    if (!sessionValidation.valid) {
+      throw new Error(`Session validation failed: ${sessionValidation.reason}`);
+    }
+
+    if (options.skipValidation !== true) {
+      const modifyCheck = await canModifyCase(user, caseNumber);
+      if (!modifyCheck.allowed) {
+        throw new Error(`Delete denied: ${modifyCheck.reason}`);
+      }
+    }
+
+    const response = await fetchDataApi(
+      user,
+      `/${encodeURIComponent(user.uid)}/${encodeURIComponent(caseNumber)}/${encodeURIComponent(fileId)}/data.json`,
+      {
+        method: 'DELETE'
+      }
+    );
+
+    if (!response.ok && response.status !== 404) {
+      throw new Error(`Failed to delete file annotations: ${response.status} ${response.statusText}`);
+    }
+
+    try {
+      await removeFileConfirmationSummary(user, caseNumber, fileId);
+    } catch (summaryError) {
+      console.warn(`Failed to update confirmation summary after delete for ${caseNumber}/${fileId}:`, summaryError);
+    }
+  } catch (error) {
+    console.error(`Error deleting annotations for ${caseNumber}/${fileId}:`, error);
+    throw error;
+  }
+};
+
+/**
+ * Check if a file has annotations.
+ */
+export const fileHasAnnotations = async (
+  user: User,
+  caseNumber: string,
+  fileId: string
+): Promise<boolean> => {
+  try {
+    const annotations = await getFileAnnotations(user, caseNumber, fileId);
+    return annotations !== null;
+  } catch (error) {
+    console.error(`Error checking annotations for ${caseNumber}/${fileId}:`, error);
+    return false;
+  }
+};

package/app/utils/data/operations/index.ts

@@ -0,0 +1,7 @@
+export * from './types';
+export * from './confirmation-summary-operations';
+export * from './case-operations';
+export * from './file-annotation-operations';
+export * from './batch-operations';
+export * from './validation-operations';
+export * from './signing-operations';