tools/ts_interfaces/attachments.ts

/**
 * @file attachments.ts
 * @description Document attachment interfaces
 * Exhibits, schedules, prior contracts, and document bundles
 */

import * as plugins from './plugins.js';
import type {
  TAttachmentType,
  TAttachmentCategory,
  TPriorContractRelationship,
  TConfidentialityLevel,
} from './types.js';

// ============================================================================
// ATTACHMENT FILE
// ============================================================================

/**
 * Storage provider types
 */
export type TStorageProvider = 'local' | 's3' | 'azure' | 'gcs';

/**
 * File metadata for attachment
 */
export interface IAttachmentFile {
  id: string;
  filename: string;
  mimeType: string;
  size: number;
  storageProvider: TStorageProvider;
  storageKey: string;
  checksum: string;
  checksumAlgorithm: 'SHA-256';
  thumbnailUrl?: string;
  previewUrl?: string;
  pageCount?: number;
  textExtraction?: string;
}

// ============================================================================
// CONTRACT ATTACHMENT
// ============================================================================

/**
 * Extended attachment for contracts
 */
export interface IContractAttachment {
  id: string;
  contractId: string;
  type: TAttachmentType;
  category: TAttachmentCategory;
  title: string;
  description?: string;
  file?: IAttachmentFile;
  inlineContent?: string;
  referencedInParagraphs: string[];
  displayOrder: number;
  versionId: string;
  attachmentVersion: number;
  addedAt: number;
  addedBy: string;
  lastModifiedAt?: number;
  lastModifiedBy?: string;
  isConfidential: boolean;
  confidentialityLevel: TConfidentialityLevel;
}

// ============================================================================
// PRIOR CONTRACT REFERENCE
// ============================================================================

/**
 * External contract reference
 */
export interface IExternalContractReference {
  title: string;
  date: number;
  parties: string[];
  summary?: string;
  documentUrl?: string;
}

/**
 * Referenced clause from prior contract
 */
export interface IReferencedClause {
  clauseReference: string;
  relevance: string;
}

/**
 * Prior contract reference
 */
export interface IPriorContractReference {
  id: string;
  contractId?: string;
  externalReference?: IExternalContractReference;
  relationshipType: TPriorContractRelationship;
  referencedClauses: IReferencedClause[];
  notes?: string;
}

// ============================================================================
// DOCUMENT BUNDLE
// ============================================================================

/**
 * Export settings for document bundle
 */
export interface IBundleExportSettings {
  includeAuditLog: boolean;
  includeComments: boolean;
  redactConfidential: boolean;
  watermark?: string;
}

/**
 * Document bundle purpose
 */
export type TBundlePurpose = 'signing_package' | 'due_diligence' | 'archive' | 'discovery' | 'custom';

/**
 * Document bundle (collection of related documents)
 */
export interface IDocumentBundle {
  id: string;
  name: string;
  description?: string;
  mainContractId: string;
  attachmentIds: string[];
  priorContractIds: string[];
  createdAt: number;
  createdBy: string;
  purpose: TBundlePurpose;
  exportSettings?: IBundleExportSettings;
}

// ============================================================================
// FACTORY FUNCTIONS
// ============================================================================

/**
 * Create a new contract attachment
 */
export function createContractAttachment(
  contractId: string,
  versionId: string,
  type: TAttachmentType,
  category: TAttachmentCategory,
  title: string,
  addedBy: string
): IContractAttachment {
  return {
    id: crypto.randomUUID(),
    contractId,
    type,
    category,
    title,
    referencedInParagraphs: [],
    displayOrder: 0,
    versionId,
    attachmentVersion: 1,
    addedAt: Date.now(),
    addedBy,
    isConfidential: false,
    confidentialityLevel: 'internal',
  };
}

/**
 * Create a prior contract reference
 */
export function createPriorContractReference(
  relationshipType: TPriorContractRelationship,
  contractId?: string,
  externalReference?: IExternalContractReference
): IPriorContractReference {
  return {
    id: crypto.randomUUID(),
    contractId,
    externalReference,
    relationshipType,
    referencedClauses: [],
  };
}

/**
 * Create a document bundle
 */
export function createDocumentBundle(
  name: string,
  mainContractId: string,
  purpose: TBundlePurpose,
  createdBy: string
): IDocumentBundle {
  return {
    id: crypto.randomUUID(),
    name,
    mainContractId,
    attachmentIds: [],
    priorContractIds: [],
    createdAt: Date.now(),
    createdBy,
    purpose,
  };
}

/**
 * Create an attachment file metadata
 */
export function createAttachmentFile(
  filename: string,
  mimeType: string,
  size: number,
  storageProvider: TStorageProvider,
  storageKey: string,
  checksum: string
): IAttachmentFile {
  return {
    id: crypto.randomUUID(),
    filename,
    mimeType,
    size,
    storageProvider,
    storageKey,
    checksum,
    checksumAlgorithm: 'SHA-256',
  };
}