@striae-org/striae 4.2.0 → 4.2.1

package/app/utils/data/index.ts

@@ -1,2 +1,12 @@
-export * from './data-operations';
+export * from './operations';
 export * from './permissions';
+
+export {
+  getConfirmationSummaryTelemetry,
+  resetConfirmationSummaryTelemetry,
+  type CaseConfirmationSummary,
+  type ConfirmationSummaryEnsureOptions,
+  type ConfirmationSummaryTelemetry,
+  type FileConfirmationSummary,
+  type UserConfirmationSummaryDocument
+} from './confirmation-summary/summary-core';

package/app/utils/data/operations/batch-operations.ts

@@ -0,0 +1,113 @@
+import type { User } from 'firebase/auth';
+
+import { canModifyCase, validateUserSession } from '../permissions';
+import { getCaseData, updateCaseData } from './case-operations';
+import { getFileAnnotations, saveFileAnnotations } from './file-annotation-operations';
+import type { BatchUpdateResult, DataOperationOptions, FileUpdate } from './types';
+
+/**
+ * Update multiple files with annotation data in a single operation.
+ */
+export const batchUpdateFiles = async (
+  user: User,
+  caseNumber: string,
+  updates: FileUpdate[],
+  options: DataOperationOptions = {}
+): Promise<BatchUpdateResult> => {
+  const result: BatchUpdateResult = {
+    successful: [],
+    failed: []
+  };
+
+  try {
+    const sessionValidation = await validateUserSession(user);
+    if (!sessionValidation.valid) {
+      throw new Error(`Session validation failed: ${sessionValidation.reason}`);
+    }
+
+    const modifyCheck = await canModifyCase(user, caseNumber);
+    if (!modifyCheck.allowed) {
+      throw new Error(`Batch update denied: ${modifyCheck.reason}`);
+    }
+
+    const perFileOptions: DataOperationOptions = {
+      ...options,
+      skipValidation: true
+    };
+
+    for (const update of updates) {
+      try {
+        await saveFileAnnotations(user, caseNumber, update.fileId, update.annotations, perFileOptions);
+        result.successful.push(update.fileId);
+      } catch (error) {
+        result.failed.push({
+          fileId: update.fileId,
+          error: error instanceof Error ? error.message : 'Unknown error'
+        });
+      }
+    }
+
+    return result;
+  } catch (error) {
+    for (const update of updates) {
+      result.failed.push({
+        fileId: update.fileId,
+        error: error instanceof Error ? error.message : 'Batch operation failed'
+      });
+    }
+    return result;
+  }
+};
+
+/**
+ * Duplicate case data from one case to another (for case renaming operations).
+ */
+export const duplicateCaseData = async (
+  user: User,
+  fromCaseNumber: string,
+  toCaseNumber: string,
+  options: { skipDestinationCheck?: boolean } = {}
+): Promise<void> => {
+  try {
+    if (!options.skipDestinationCheck) {
+      const accessResult = await canModifyCase(user, toCaseNumber);
+      if (!accessResult.allowed) {
+        throw new Error(`User does not have permission to create or modify case ${toCaseNumber}: ${accessResult.reason || 'Access denied'}`);
+      }
+    }
+
+    const sourceCaseData = await getCaseData(user, fromCaseNumber);
+    if (!sourceCaseData) {
+      throw new Error(`Source case ${fromCaseNumber} not found`);
+    }
+
+    const newCaseData = {
+      ...sourceCaseData,
+      caseNumber: toCaseNumber,
+      updatedAt: new Date().toISOString()
+    };
+
+    await updateCaseData(user, toCaseNumber, newCaseData);
+
+    if (sourceCaseData.files && sourceCaseData.files.length > 0) {
+      const updates: FileUpdate[] = [];
+
+      for (const file of sourceCaseData.files) {
+        const annotations = await getFileAnnotations(user, fromCaseNumber, file.id);
+        if (annotations) {
+          updates.push({
+            fileId: file.id,
+            annotations
+          });
+        }
+      }
+
+      if (updates.length > 0) {
+        await batchUpdateFiles(user, toCaseNumber, updates);
+      }
+    }
+  } catch (error) {
+    console.error(`Error duplicating case data from ${fromCaseNumber} to ${toCaseNumber}:`, error);
+    throw error;
+  }
+};

package/app/utils/data/operations/case-operations.ts

@@ -0,0 +1,168 @@
+import type { User } from 'firebase/auth';
+import type { CaseData } from '~/types';
+
+import { fetchDataApi } from '../../api';
+import { canAccessCase, canModifyCase, validateUserSession } from '../permissions';
+import type { DataOperationOptions } from './types';
+
+/**
+ * Get case data from R2 storage with validation and error handling.
+ */
+export const getCaseData = async (
+  user: User,
+  caseNumber: string,
+  options: DataOperationOptions = {}
+): Promise<CaseData | null> => {
+  try {
+    const sessionValidation = await validateUserSession(user);
+    if (!sessionValidation.valid) {
+      throw new Error(`Session validation failed: ${sessionValidation.reason}`);
+    }
+
+    if (options.skipValidation !== true) {
+      const accessCheck = await canAccessCase(user, caseNumber);
+      if (!accessCheck.allowed) {
+        return null;
+      }
+    }
+
+    if (!caseNumber || typeof caseNumber !== 'string' || caseNumber.trim() === '') {
+      throw new Error('Invalid case number provided');
+    }
+
+    const response = await fetchDataApi(
+      user,
+      `/${encodeURIComponent(user.uid)}/${encodeURIComponent(caseNumber)}/data.json`,
+      {
+        method: 'GET'
+      }
+    );
+
+    if (response.status === 404) {
+      return null;
+    }
+
+    if (!response.ok) {
+      throw new Error(`Failed to fetch case data: ${response.status} ${response.statusText}`);
+    }
+
+    const caseData = await response.json() as CaseData;
+    return caseData;
+  } catch (error) {
+    console.error(`Error fetching case data for ${caseNumber}:`, error);
+    throw error;
+  }
+};
+
+/**
+ * Update case data in R2 storage with validation and timestamps.
+ */
+export const updateCaseData = async (
+  user: User,
+  caseNumber: string,
+  caseData: CaseData,
+  options: DataOperationOptions = {}
+): Promise<void> => {
+  try {
+    const sessionValidation = await validateUserSession(user);
+    if (!sessionValidation.valid) {
+      throw new Error(`Session validation failed: ${sessionValidation.reason}`);
+    }
+
+    const modifyCheck = await canModifyCase(user, caseNumber);
+    if (!modifyCheck.allowed) {
+      throw new Error(`Modification denied: ${modifyCheck.reason}`);
+    }
+
+    if (!caseNumber || typeof caseNumber !== 'string') {
+      throw new Error('Invalid case number provided');
+    }
+
+    if (!caseData || typeof caseData !== 'object') {
+      throw new Error('Invalid case data provided');
+    }
+
+    const dataToSave = options.includeTimestamp !== false
+      ? {
+          ...caseData,
+          updatedAt: new Date().toISOString()
+        }
+      : caseData;
+
+    const response = await fetchDataApi(
+      user,
+      `/${encodeURIComponent(user.uid)}/${encodeURIComponent(caseNumber)}/data.json`,
+      {
+        method: 'PUT',
+        headers: {
+          'Content-Type': 'application/json'
+        },
+        body: JSON.stringify(dataToSave)
+      }
+    );
+
+    if (!response.ok) {
+      throw new Error(`Failed to update case data: ${response.status} ${response.statusText}`);
+    }
+  } catch (error) {
+    console.error(`Error updating case data for ${caseNumber}:`, error);
+    throw error;
+  }
+};
+
+/**
+ * Delete case data from R2 storage with validation.
+ */
+export const deleteCaseData = async (
+  user: User,
+  caseNumber: string,
+  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(`Delete denied: ${modifyCheck.reason}`);
+      }
+    }
+
+    const response = await fetchDataApi(
+      user,
+      `/${encodeURIComponent(user.uid)}/${encodeURIComponent(caseNumber)}/data.json`,
+      {
+        method: 'DELETE'
+      }
+    );
+
+    if (!response.ok && response.status !== 404) {
+      throw new Error(`Failed to delete case data: ${response.status} ${response.statusText}`);
+    }
+  } catch (error) {
+    console.error(`Error deleting case data for ${caseNumber}:`, error);
+    throw error;
+  }
+};
+
+/**
+ * Check if a case exists in storage.
+ */
+export const caseExists = async (
+  user: User,
+  caseNumber: string
+): Promise<boolean> => {
+  try {
+    const caseData = await getCaseData(user, caseNumber);
+    return caseData !== null;
+  } catch (error) {
+    if (error instanceof Error && error.message.includes('Access denied')) {
+      return false;
+    }
+    console.error(`Error checking case existence for ${caseNumber}:`, error);
+    return false;
+  }
+};

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);
+};