hazo_files 1.4.0 → 1.4.2

package/README.md

@@ -16,7 +16,9 @@ A powerful, modular file management package for Node.js and React applications w
 - **Extraction Data Management**: Track and manage LLM-extracted metadata with merge strategies
 - **LLM Integration**: Built-in support for hazo_llm_api document/image extraction
 - **Upload + Extract Workflow**: Combined service for uploading files with automatic LLM extraction and naming
+- **File Reference Tracking**: Multi-entity file references with orphan detection, soft delete, and lifecycle management
 - **File Change Detection**: xxHash-based content hashing for efficient change detection
+- **Schema Migrations**: Built-in V2 migration utilities for adding reference tracking to existing databases
 - **TypeScript**: Full type safety and IntelliSense support
 - **OAuth Integration**: Built-in Google Drive OAuth authentication
 - **Progress Tracking**: Upload/download progress callbacks
@@ -50,6 +52,23 @@ npm install server-only       # Server-side safety (recommended)
 # Note: xxhash-wasm is included automatically as a dependency
 ```
 
+### Tailwind CSS v4 Setup (Required for UI Components)
+
+If you're using Tailwind CSS v4 with the UI components, you must add a `@source` directive to your CSS file to ensure Tailwind scans the package's files for utility classes.
+
+Add this to your `globals.css` or main CSS file AFTER the tailwindcss import:
+
+```css
+@import "tailwindcss";
+
+/* Required: Enable Tailwind to scan hazo_files package for utility classes */
+@source "../node_modules/hazo_files/dist/ui";
+```
+
+Without this directive, Tailwind v4's JIT compiler will not generate CSS for the utility classes used in hazo_files components (like `hover:bg-gray-100`, `text-sm`, `rounded-md`, etc.), resulting in broken styling.
+
+**Note**: This is only required for Tailwind v4. Earlier versions of Tailwind automatically scan `node_modules` and do not need this configuration.
+
 ## Quick Start
 
 ### Basic Usage (Server-side)
@@ -1175,6 +1194,101 @@ const autoResult = await extractionService.extract(
 );
 ```
 
+## File Reference Tracking
+
+Track which entities (form fields, chat messages, etc.) reference each file. Multiple entities can reference the same file, enabling shared files without duplication.
+
+### Adding and Removing References
+
+```typescript
+import { TrackedFileManager } from 'hazo_files';
+
+// Upload a file with an initial reference
+const result = await trackedManager.uploadFileWithRef(buffer, '/docs/report.pdf', {
+  scope_id: 'workspace-123',
+  uploaded_by: 'user-456',
+  ref: {
+    entity_type: 'form_field',
+    entity_id: 'field-789',
+    created_by: 'user-456',
+  },
+});
+// result.data.file_id, result.data.ref_id
+
+// Add another reference to the same file
+await trackedManager.addRef(fileId, {
+  entity_type: 'chat_message',
+  entity_id: 'msg-abc',
+});
+
+// Remove a specific reference
+const { remaining_refs } = await trackedManager.removeRef(fileId, refId);
+
+// Get file with status info
+const fileStatus = await trackedManager.getFileById(fileId);
+// { record, refs: FileRef[], is_orphaned: boolean }
+```
+
+### Orphan Detection and Cleanup
+
+```typescript
+// Find files with zero references
+const orphans = await trackedManager.findOrphanedFiles({
+  olderThanMs: 7 * 24 * 60 * 60 * 1000, // 7 days old
+  scope_id: 'workspace-123',
+});
+
+// Clean up orphaned files (delete physical files + DB records)
+const { cleaned, errors } = await trackedManager.cleanupOrphanedFiles({
+  olderThanMs: 30 * 24 * 60 * 60 * 1000,
+  softDeleteOnly: false, // true to only mark as soft_deleted
+});
+
+// Soft-delete a specific file
+await trackedManager.softDeleteFile(fileId);
+
+// Verify physical file existence
+const exists = await trackedManager.verifyFileExistence(fileId);
+```
+
+### Database Migration (Existing Databases)
+
+If you have an existing `hazo_files` table, run the V2 migration to add reference tracking columns:
+
+```typescript
+import { migrateToV2, backfillV2Defaults, HAZO_FILES_MIGRATION_V2 } from 'hazo_files';
+
+// Using the migration helper
+await migrateToV2(
+  { run: (sql) => db.exec(sql) }, // SQLite
+  'sqlite'
+);
+await backfillV2Defaults({ run: (sql) => db.exec(sql) }, 'sqlite');
+
+// Or run statements manually
+for (const stmt of HAZO_FILES_MIGRATION_V2.sqlite.alterStatements) {
+  try { await db.run(stmt); } catch { /* column exists */ }
+}
+for (const idx of HAZO_FILES_MIGRATION_V2.sqlite.indexes) {
+  await db.run(idx);
+}
+```
+
+New tables created with `HAZO_FILES_TABLE_SCHEMA` already include V2 columns.
+
+### Reference Tracking Types
+
+```typescript
+import type {
+  FileRef,           // Individual reference from entity to file
+  FileMetadataRecordV2,  // Extended record with refs, status, scope
+  FileWithStatus,    // Rich view: record + parsed refs + is_orphaned
+  FileStatus,        // 'active' | 'orphaned' | 'soft_deleted' | 'missing'
+  AddRefOptions,     // Options for adding a reference
+  RemoveRefsCriteria, // Criteria for bulk ref removal
+} from 'hazo_files';
+```
+
 ## File Change Detection
 
 Detect file content changes using fast xxHash hashing.

package/dist/index.d.mts

@@ -179,6 +179,12 @@ interface FileMetadataInput {
     file_hash?: string;
     /** File size in bytes */
     file_size?: number;
+    /** Scope ID for organizational grouping (V2) */
+    scope_id?: string;
+    /** User who uploaded the file (V2) */
+    uploaded_by?: string;
+    /** Original filename at upload time (V2) */
+    original_filename?: string;
 }
 /**
  * Input for updating an existing metadata record
@@ -354,6 +360,135 @@ interface ListNamingConventionsOptions {
     includeGlobal?: boolean;
 }
 
+/**
+ * Reference Tracking Types for hazo_files
+ * Supports multi-entity file references with lifecycle management
+ */
+
+/** Status of a file in the system */
+type FileStatus = 'active' | 'orphaned' | 'soft_deleted' | 'missing';
+/** Visibility level for a file reference */
+type FileRefVisibility = 'public' | 'private' | 'internal';
+/**
+ * A reference from an entity to a file.
+ * Multiple entities can reference the same file.
+ */
+interface FileRef {
+    /** Unique ID for this reference */
+    ref_id: string;
+    /** Type of entity referencing the file (e.g., 'form_field', 'chat_message') */
+    entity_type: string;
+    /** ID of the entity referencing the file */
+    entity_id: string;
+    /** ISO timestamp when reference was created */
+    created_at: string;
+    /** User or system that created this reference */
+    created_by?: string;
+    /** Visibility of this reference */
+    visibility?: FileRefVisibility;
+    /** Optional label for the reference */
+    label?: string;
+    /** Optional metadata for the reference */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Extended metadata record with reference tracking fields.
+ * Extends FileMetadataRecord with V2 columns.
+ */
+interface FileMetadataRecordV2 extends FileMetadataRecord {
+    /** JSON string of FileRef[] - parsed by service methods */
+    file_refs: string;
+    /** Number of active references (denormalized for queries) */
+    ref_count: number;
+    /** Current file status */
+    status: FileStatus;
+    /** Scope ID for organizational grouping (e.g., workspace, tenant) */
+    scope_id?: string | null;
+    /** User who uploaded the file */
+    uploaded_by?: string | null;
+    /** Original filename at upload time */
+    original_filename?: string | null;
+    /** ISO timestamp when storage was last verified */
+    storage_verified_at?: string | null;
+    /** ISO timestamp when file was soft-deleted */
+    deleted_at?: string | null;
+}
+/**
+ * Options for adding a reference to a file
+ */
+interface AddRefOptions {
+    /** Type of entity referencing the file */
+    entity_type: string;
+    /** ID of the entity referencing the file */
+    entity_id: string;
+    /** User creating the reference */
+    created_by?: string;
+    /** Visibility of the reference */
+    visibility?: FileRefVisibility;
+    /** Optional label */
+    label?: string;
+    /** Optional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Criteria for removing references.
+ * All specified fields must match (AND semantics).
+ */
+interface RemoveRefsCriteria {
+    /** Match by entity type */
+    entity_type?: string;
+    /** Match by entity ID */
+    entity_id?: string;
+    /** Match by scope ID on the file record */
+    scope_id?: string;
+    /** Match by specific file ID */
+    file_id?: string;
+}
+/**
+ * Rich status view of a file with parsed references
+ */
+interface FileWithStatus {
+    /** Full metadata record (V2) */
+    record: FileMetadataRecordV2;
+    /** Parsed file references */
+    refs: FileRef[];
+    /** Whether the file has zero references */
+    is_orphaned: boolean;
+}
+/**
+ * Options for finding orphaned files
+ */
+interface FindOrphanedOptions {
+    /** Only find orphans older than this duration (ISO 8601 duration or ms) */
+    olderThanMs?: number;
+    /** Filter by scope */
+    scope_id?: string;
+    /** Filter by storage type */
+    storage_type?: StorageProvider;
+    /** Maximum number of results */
+    limit?: number;
+}
+/**
+ * Options for cleaning up orphaned files
+ */
+interface CleanupOrphanedOptions extends FindOrphanedOptions {
+    /** If true, only soft-delete rather than permanently removing (default: false) */
+    softDeleteOnly?: boolean;
+    /** If true, also delete physical files (default: true) */
+    deletePhysicalFiles?: boolean;
+}
+/**
+ * Options for uploading a file with an initial reference
+ */
+interface UploadWithRefOptions {
+    /** Reference to add after upload */
+    ref?: AddRefOptions;
+    /** Scope ID for the file */
+    scope_id?: string;
+    /** User performing the upload */
+    uploaded_by?: string;
+}
+
 /**
  * Core types for the hazo_files package
  */
@@ -813,6 +948,67 @@ declare class FileMetadataService {
      * Clear all extractions for a file
      */
     clearExtractions(path: string, storageType: StorageProvider): Promise<boolean>;
+    /**
+     * Find a record by ID
+     */
+    findById(id: string): Promise<FileMetadataRecord | null>;
+    /**
+     * Find multiple records by IDs
+     */
+    findByIds(ids: string[]): Promise<FileMetadataRecord[]>;
+    /**
+     * Add a reference to a file
+     * @returns The new ref_id, or null on failure
+     */
+    addRef(fileId: string, options: AddRefOptions): Promise<{
+        ref_id: string;
+    } | null>;
+    /**
+     * Remove a specific reference from a file
+     * @returns Remaining ref count, or null on failure
+     */
+    removeRef(fileId: string, refId: string): Promise<{
+        remaining_refs: number;
+    } | null>;
+    /**
+     * Remove references matching criteria across all records.
+     * Scans all records and removes matching refs (AND semantics).
+     */
+    removeRefsByCriteria(criteria: RemoveRefsCriteria): Promise<{
+        removed_count: number;
+    }>;
+    /**
+     * Helper: remove matching refs from a single record
+     */
+    private removeRefsFromRecord;
+    /**
+     * Get all references for a file
+     */
+    getRefs(fileId: string): Promise<FileRef[] | null>;
+    /**
+     * Get a file with its status and parsed refs
+     */
+    getFileWithStatus(fileId: string): Promise<FileWithStatus | null>;
+    /**
+     * Get multiple files with status
+     */
+    getFilesWithStatus(fileIds: string[]): Promise<FileWithStatus[]>;
+    /**
+     * Update the status of a file
+     */
+    updateStatus(fileId: string, status: FileStatus): Promise<boolean>;
+    /**
+     * Soft-delete a file (set status to soft_deleted, record deleted_at)
+     */
+    softDelete(fileId: string): Promise<boolean>;
+    /**
+     * Update specific V2 fields on a record
+     */
+    updateFields(fileId: string, fields: Partial<Pick<FileMetadataRecordV2, 'scope_id' | 'uploaded_by' | 'original_filename' | 'storage_verified_at' | 'status'>>): Promise<boolean>;
+    /**
+     * Find orphaned files (zero references)
+     */
+    findOrphaned(options?: FindOrphanedOptions): Promise<FileWithStatus[]>;
 }
 /**
  * Create a FileMetadataService instance
@@ -953,6 +1149,52 @@ declare class TrackedFileManager extends FileManager {
      * @returns Stored size in bytes or null if not found/not tracked
      */
     getStoredSize(path: string): Promise<number | null>;
+    /**
+     * Add a reference to a file
+     */
+    addRef(fileId: string, options: AddRefOptions): Promise<{
+        ref_id: string;
+    } | null>;
+    /**
+     * Remove a reference from a file
+     */
+    removeRef(fileId: string, refId: string): Promise<{
+        remaining_refs: number;
+    } | null>;
+    /**
+     * Get a file by its database ID with status information
+     */
+    getFileById(fileId: string): Promise<FileWithStatus | null>;
+    /**
+     * Get multiple files by their database IDs with status information
+     */
+    getFilesById(fileIds: string[]): Promise<FileWithStatus[]>;
+    /**
+     * Soft-delete a file (marks as soft_deleted, does not remove physical file)
+     */
+    softDeleteFile(fileId: string): Promise<boolean>;
+    /**
+     * Find orphaned files (files with zero references)
+     */
+    findOrphanedFiles(options?: FindOrphanedOptions): Promise<FileWithStatus[]>;
+    /**
+     * Cleanup orphaned files — removes physical files and/or DB records
+     */
+    cleanupOrphanedFiles(options?: CleanupOrphanedOptions): Promise<{
+        cleaned: number;
+        errors: string[];
+    }>;
+    /**
+     * Verify that a file's physical storage exists and update its status
+     */
+    verifyFileExistence(fileId: string): Promise<boolean | null>;
+    /**
+     * Upload a file and optionally add an initial reference
+     */
+    uploadFileWithRef(source: string | Buffer | ReadableStream, remotePath: string, options?: TrackedUploadOptions & UploadWithRefOptions): Promise<OperationResult<FileItem & {
+        file_id?: string;
+        ref_id?: string;
+    }>>;
 }
 /**
  * Create a new TrackedFileManager instance
@@ -1485,6 +1727,22 @@ interface HazoFilesColumnDefinitions {
     file_size: 'INTEGER' | 'BIGINT';
     /** ISO timestamp when file content last changed */
     file_changed_at: 'TEXT' | 'TIMESTAMP';
+    /** JSON string of FileRef[] - reference tracking (V2) */
+    file_refs: 'TEXT';
+    /** Number of active references (V2) */
+    ref_count: 'INTEGER';
+    /** File status: active, orphaned, soft_deleted, missing (V2) */
+    status: 'TEXT';
+    /** Scope ID for organizational grouping (V2) */
+    scope_id: 'TEXT' | 'UUID';
+    /** User who uploaded the file (V2) */
+    uploaded_by: 'TEXT' | 'UUID';
+    /** ISO timestamp when storage was last verified (V2) */
+    storage_verified_at: 'TEXT' | 'TIMESTAMP';
+    /** ISO timestamp when file was soft-deleted (V2) */
+    deleted_at: 'TEXT' | 'TIMESTAMP';
+    /** Original filename at upload time (V2) */
+    original_filename: 'TEXT';
 }
 /**
  * Schema definition for a specific database type
@@ -1547,6 +1805,57 @@ declare const HAZO_FILES_TABLE_SCHEMA: HazoFilesTableSchema;
  * @returns DDL and index statements with the custom table name
  */
 declare function getSchemaForTable(tableName: string, dbType: 'sqlite' | 'postgres'): DatabaseSchemaDefinition;
+/**
+ * Migration schema for adding V2 reference tracking columns to existing tables.
+ * Idempotent — safe to run multiple times (uses IF NOT EXISTS for indexes,
+ * and ALTER TABLE ADD COLUMN is ignored if column exists in SQLite).
+ *
+ * For PostgreSQL, columns are added with IF NOT EXISTS (PG 9.6+).
+ *
+ * @example
+ * ```typescript
+ * import { HAZO_FILES_MIGRATION_V2 } from 'hazo_files';
+ *
+ * // SQLite
+ * for (const stmt of HAZO_FILES_MIGRATION_V2.sqlite.alterStatements) {
+ *   try { await db.run(stmt); } catch { /* column already exists *\/ }
+ * }
+ * for (const idx of HAZO_FILES_MIGRATION_V2.sqlite.indexes) {
+ *   await db.run(idx);
+ * }
+ *
+ * // PostgreSQL
+ * for (const stmt of HAZO_FILES_MIGRATION_V2.postgres.alterStatements) {
+ *   await client.query(stmt);
+ * }
+ * for (const idx of HAZO_FILES_MIGRATION_V2.postgres.indexes) {
+ *   await client.query(idx);
+ * }
+ * ```
+ */
+interface MigrationSchemaDefinition {
+    /** ALTER TABLE statements to add new columns */
+    alterStatements: string[];
+    /** CREATE INDEX statements for new columns */
+    indexes: string[];
+    /** UPDATE statement to backfill defaults for existing records */
+    backfill: string;
+}
+interface HazoFilesMigrationV2 {
+    /** Default table name */
+    tableName: string;
+    /** SQLite migration statements */
+    sqlite: MigrationSchemaDefinition;
+    /** PostgreSQL migration statements */
+    postgres: MigrationSchemaDefinition;
+    /** New column names added in V2 */
+    newColumns: readonly string[];
+}
+declare const HAZO_FILES_MIGRATION_V2: HazoFilesMigrationV2;
+/**
+ * Get migration statements for a custom table name
+ */
+declare function getMigrationForTable(tableName: string, dbType: 'sqlite' | 'postgres'): MigrationSchemaDefinition;
 /**
  * Default table name for naming conventions
  */
@@ -1617,6 +1926,47 @@ declare const HAZO_FILES_NAMING_TABLE_SCHEMA: HazoFilesNamingTableSchema;
  */
 declare function getNamingSchemaForTable(tableName: string, dbType: 'sqlite' | 'postgres'): DatabaseSchemaDefinition;
 
+/**
+ * Migration: Add Reference Tracking (V2)
+ *
+ * Adds reference tracking columns to an existing hazo_files table.
+ * Idempotent — safe to run multiple times.
+ */
+/**
+ * Executor interface for running SQL statements.
+ * Compatible with common database adapters (better-sqlite3, pg, hazo_connect).
+ */
+interface MigrationExecutor {
+    run(sql: string): Promise<void> | void;
+}
+/**
+ * Run the V2 migration: add reference tracking columns and indexes.
+ *
+ * @param executor - Object with a `run(sql)` method
+ * @param dbType - Database type ('sqlite' | 'postgres')
+ * @param tableName - Custom table name (defaults to 'hazo_files')
+ *
+ * @example
+ * ```typescript
+ * import { migrateToV2 } from 'hazo_files';
+ *
+ * // SQLite with better-sqlite3
+ * await migrateToV2({ run: (sql) => db.exec(sql) }, 'sqlite');
+ *
+ * // PostgreSQL with pg
+ * await migrateToV2({ run: (sql) => client.query(sql) }, 'postgres');
+ * ```
+ */
+declare function migrateToV2(executor: MigrationExecutor, dbType: 'sqlite' | 'postgres', tableName?: string): Promise<void>;
+/**
+ * Backfill V2 defaults for existing records that have NULL V2 columns.
+ *
+ * @param executor - Object with a `run(sql)` method
+ * @param dbType - Database type ('sqlite' | 'postgres')
+ * @param tableName - Custom table name (defaults to 'hazo_files')
+ */
+declare function backfillV2Defaults(executor: MigrationExecutor, dbType: 'sqlite' | 'postgres', tableName?: string): Promise<void>;
+
 /**
  * Common utility functions
  */
@@ -2391,4 +2741,45 @@ declare function hashesEqual(hash1: string | null | undefined, hash2: string | n
  */
 declare function hasFileContentChanged(oldHash: string | null | undefined, newBuffer: Buffer): Promise<boolean>;
 
-export { ALL_SYSTEM_VARIABLES, type AddExtractionOptions, type AuthCallbacks, AuthenticationError, ConfigurationError, type CreateFolderOptions, type CrudServiceLike, DEFAULT_DATE_FORMATS, type DatabaseSchemaDefinition, type DatabaseTrackingConfig, DirectoryExistsError, DirectoryNotEmptyError, DirectoryNotFoundError, type DownloadOptions, type ExtractionData, type ExtractionOptions, type ExtractionResult, type FileBrowserState, type FileDataStructure, FileExistsError, type FileInfo, type FileItem, FileManager, type FileManagerOptions, type FileMetadataInput, type FileMetadataRecord, FileMetadataService, type FileMetadataServiceOptions, type FileMetadataUpdate, FileNotFoundError, type FileSystemItem, FileTooLargeError, type FolderItem, type GeneratedNameResult, type GoogleAuthConfig, GoogleDriveAuth, type GoogleDriveConfig, GoogleDriveModule, HAZO_FILES_DEFAULT_TABLE_NAME, HAZO_FILES_NAMING_DEFAULT_TABLE_NAME, HAZO_FILES_NAMING_TABLE_SCHEMA, HAZO_FILES_TABLE_SCHEMA, type HazoFilesColumnDefinitions, type HazoFilesConfig, HazoFilesError, type HazoFilesNamingColumnDefinitions, type HazoFilesNamingTableSchema, type HazoFilesTableSchema, type HazoLLMInstance, InvalidExtensionError, InvalidPathError, LLMExtractionService, type LLMFactory, type LLMProvider, type ListNamingConventionsOptions, type ListOptions, type LocalStorageConfig, LocalStorageModule, type MetadataLogger, type MoveOptions, type NameGenerationOptions, type NamingConventionInput, type NamingConventionRecord, NamingConventionService, type NamingConventionServiceOptions, type NamingConventionType, type NamingConventionUpdate, type NamingRuleConfiguratorProps, type NamingRuleHistoryEntry, type NamingRuleSchema, type NamingVariable, OperationError, type OperationResult, type ParsedNamingConvention, type PatternSegment, PermissionDeniedError, type ProgressCallback, type RemoveExtractionOptions, type RenameOptions, SYSTEM_COUNTER_VARIABLES, SYSTEM_DATE_VARIABLES, SYSTEM_FILE_VARIABLES, type StorageModule, type StorageProvider, type TokenData, TrackedFileManager, type TrackedFileManagerFullOptions, type TrackedFileManagerOptions, type TrackedUploadOptions, type TreeNode, type UploadExtractOptions, type UploadExtractResult, UploadExtractService, type UploadOptions, type UseNamingRuleActions, type UseNamingRuleReturn, type UseNamingRuleState, type VariableCategory, addExtractionToFileData, clearExtractions, clonePattern, computeFileHash, computeFileHashFromStream, computeFileHashSync, computeFileInfo, createAndInitializeModule, createEmptyFileDataStructure, createEmptyNamingRuleSchema, createFileItem, createFileManager, createFileMetadataService, createFolderItem, createGoogleDriveAuth, createGoogleDriveModule, createInitializedFileManager, createInitializedTrackedFileManager, createLLMExtractionService, createLiteralSegment, createLocalModule, createModule, createNamingConventionService, createTrackedFileManager, createUploadExtractService, createVariableSegment, deepMerge, errorResult, filterItems, formatBytes, formatCounter, formatDateToken, generateExtractionId, generateId, generatePreviewName, generateSampleConfig, generateSegmentId, getBaseName, getBreadcrumbs, getDirName, getExtension, getExtensionFromMime, getExtractionById, getExtractionCount, getExtractions, getFileCategory, getFileMetadataValues, getMergedData, getMimeType, getNameWithoutExtension, getNamingSchemaForTable, getParentPath, getPathSegments, getRegisteredProviders, getRelativePath, getSchemaForTable, getSystemVariablePreviewValues, hasExtension, hasExtractionStructure, hasFileContentChanged, hashesEqual, hazo_files_generate_file_name, hazo_files_generate_folder_name, isAudio, isChildPath, isCounterVariable, isDateVariable, isDocument, isFile, isFileMetadataVariable, isFolder, isImage, isPreviewable, isProviderRegistered, isText, isVideo, joinPath, loadConfig, loadConfigAsync, normalizePath, parseConfig, parseFileData, parsePatternString, patternToString, recalculateMergedData, registerModule, removeExtractionById, removeExtractionByIndex, sanitizeFilename, saveConfig, sortItems, stringifyFileData, successResult, updateExtractionById, validateExtractionData, validateFileDataStructure, validateNamingRuleSchema, validatePath };
+/**
+ * Reference Tracking Utilities
+ * Pure functions for managing file references within the file_refs JSON field
+ */
+
+/**
+ * Generate a unique reference ID
+ */
+declare function generateRefId(): string;
+/**
+ * Parse a JSON string into FileRef array.
+ * Returns empty array on invalid input.
+ */
+declare function parseFileRefs(json: string | null | undefined): FileRef[];
+/**
+ * Serialize FileRef array to JSON string
+ */
+declare function stringifyFileRefs(refs: FileRef[]): string;
+/**
+ * Create a FileRef from AddRefOptions
+ */
+declare function createFileRef(options: AddRefOptions): FileRef;
+/**
+ * Remove a ref by ref_id (immutable)
+ */
+declare function removeRefFromArray(refs: FileRef[], refId: string): FileRef[];
+/**
+ * Remove refs matching criteria from array (immutable).
+ * All specified criteria fields must match (AND semantics).
+ */
+declare function removeRefsByCriteriaFromArray(refs: FileRef[], criteria: Omit<RemoveRefsCriteria, 'file_id' | 'scope_id'>): FileRef[];
+/**
+ * Safely cast a FileMetadataRecord to FileMetadataRecordV2.
+ * Missing V2 fields are defaulted.
+ */
+declare function toV2Record(record: FileMetadataRecord): FileMetadataRecordV2;
+/**
+ * Build a FileWithStatus view from a record
+ */
+declare function buildFileWithStatus(record: FileMetadataRecord): FileWithStatus;
+
+export { ALL_SYSTEM_VARIABLES, type AddExtractionOptions, type AddRefOptions, type AuthCallbacks, AuthenticationError, type CleanupOrphanedOptions, ConfigurationError, type CreateFolderOptions, type CrudServiceLike, DEFAULT_DATE_FORMATS, type DatabaseSchemaDefinition, type DatabaseTrackingConfig, DirectoryExistsError, DirectoryNotEmptyError, DirectoryNotFoundError, type DownloadOptions, type ExtractionData, type ExtractionOptions, type ExtractionResult, type FileBrowserState, type FileDataStructure, FileExistsError, type FileInfo, type FileItem, FileManager, type FileManagerOptions, type FileMetadataInput, type FileMetadataRecord, type FileMetadataRecordV2, FileMetadataService, type FileMetadataServiceOptions, type FileMetadataUpdate, FileNotFoundError, type FileRef, type FileRefVisibility, type FileStatus, type FileSystemItem, FileTooLargeError, type FileWithStatus, type FindOrphanedOptions, type FolderItem, type GeneratedNameResult, type GoogleAuthConfig, GoogleDriveAuth, type GoogleDriveConfig, GoogleDriveModule, HAZO_FILES_DEFAULT_TABLE_NAME, HAZO_FILES_MIGRATION_V2, HAZO_FILES_NAMING_DEFAULT_TABLE_NAME, HAZO_FILES_NAMING_TABLE_SCHEMA, HAZO_FILES_TABLE_SCHEMA, type HazoFilesColumnDefinitions, type HazoFilesConfig, HazoFilesError, type HazoFilesMigrationV2, type HazoFilesNamingColumnDefinitions, type HazoFilesNamingTableSchema, type HazoFilesTableSchema, type HazoLLMInstance, InvalidExtensionError, InvalidPathError, LLMExtractionService, type LLMFactory, type LLMProvider, type ListNamingConventionsOptions, type ListOptions, type LocalStorageConfig, LocalStorageModule, type MetadataLogger, type MigrationExecutor, type MigrationSchemaDefinition, type MoveOptions, type NameGenerationOptions, type NamingConventionInput, type NamingConventionRecord, NamingConventionService, type NamingConventionServiceOptions, type NamingConventionType, type NamingConventionUpdate, type NamingRuleConfiguratorProps, type NamingRuleHistoryEntry, type NamingRuleSchema, type NamingVariable, OperationError, type OperationResult, type ParsedNamingConvention, type PatternSegment, PermissionDeniedError, type ProgressCallback, type RemoveExtractionOptions, type RemoveRefsCriteria, type RenameOptions, SYSTEM_COUNTER_VARIABLES, SYSTEM_DATE_VARIABLES, SYSTEM_FILE_VARIABLES, type StorageModule, type StorageProvider, type TokenData, TrackedFileManager, type TrackedFileManagerFullOptions, type TrackedFileManagerOptions, type TrackedUploadOptions, type TreeNode, type UploadExtractOptions, type UploadExtractResult, UploadExtractService, type UploadOptions, type UploadWithRefOptions, type UseNamingRuleActions, type UseNamingRuleReturn, type UseNamingRuleState, type VariableCategory, addExtractionToFileData, backfillV2Defaults, buildFileWithStatus, clearExtractions, clonePattern, computeFileHash, computeFileHashFromStream, computeFileHashSync, computeFileInfo, createAndInitializeModule, createEmptyFileDataStructure, createEmptyNamingRuleSchema, createFileItem, createFileManager, createFileMetadataService, createFileRef, createFolderItem, createGoogleDriveAuth, createGoogleDriveModule, createInitializedFileManager, createInitializedTrackedFileManager, createLLMExtractionService, createLiteralSegment, createLocalModule, createModule, createNamingConventionService, createTrackedFileManager, createUploadExtractService, createVariableSegment, deepMerge, errorResult, filterItems, formatBytes, formatCounter, formatDateToken, generateExtractionId, generateId, generatePreviewName, generateRefId, generateSampleConfig, generateSegmentId, getBaseName, getBreadcrumbs, getDirName, getExtension, getExtensionFromMime, getExtractionById, getExtractionCount, getExtractions, getFileCategory, getFileMetadataValues, getMergedData, getMigrationForTable, getMimeType, getNameWithoutExtension, getNamingSchemaForTable, getParentPath, getPathSegments, getRegisteredProviders, getRelativePath, getSchemaForTable, getSystemVariablePreviewValues, hasExtension, hasExtractionStructure, hasFileContentChanged, hashesEqual, hazo_files_generate_file_name, hazo_files_generate_folder_name, isAudio, isChildPath, isCounterVariable, isDateVariable, isDocument, isFile, isFileMetadataVariable, isFolder, isImage, isPreviewable, isProviderRegistered, isText, isVideo, joinPath, loadConfig, loadConfigAsync, migrateToV2, normalizePath, parseConfig, parseFileData, parseFileRefs, parsePatternString, patternToString, recalculateMergedData, registerModule, removeExtractionById, removeExtractionByIndex, removeRefFromArray, removeRefsByCriteriaFromArray, sanitizeFilename, saveConfig, sortItems, stringifyFileData, stringifyFileRefs, successResult, toV2Record, updateExtractionById, validateExtractionData, validateFileDataStructure, validateNamingRuleSchema, validatePath };