hazo_files 2.0.0 → 2.1.1

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+import { Readable } from 'node:stream';
 import { OAuth2Client } from 'google-auth-library';
 
 /**
@@ -396,7 +397,7 @@ type FileRefVisibility = 'public' | 'private' | 'internal';
  * A reference from an entity to a file.
  * Multiple entities can reference the same file.
  */
-interface FileRef {
+interface FileRef$1 {
     /** Unique ID for this reference */
     ref_id: string;
     /** Type of entity referencing the file (e.g., 'form_field', 'chat_message') */
@@ -480,7 +481,7 @@ interface FileWithStatus {
     /** Full metadata record (V2) */
     record: FileMetadataRecordV2;
     /** Parsed file references */
-    refs: FileRef[];
+    refs: FileRef$1[];
     /** Whether the file has zero references */
     is_orphaned: boolean;
 }
@@ -878,7 +879,7 @@ declare class FileMetadataService {
     /**
      * Get all references for a file
      */
-    getRefs(fileId: string): Promise<FileRef[] | null>;
+    getRefs(fileId: string): Promise<FileRef$1[] | null>;
     /**
      * Get a file with its status and parsed refs
      */
@@ -3256,24 +3257,24 @@ 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[];
+declare function parseFileRefs(json: string | null | undefined): FileRef$1[];
 /**
  * Serialize FileRef array to JSON string
  */
-declare function stringifyFileRefs(refs: FileRef[]): string;
+declare function stringifyFileRefs(refs: FileRef$1[]): string;
 /**
  * Create a FileRef from AddRefOptions
  */
-declare function createFileRef(options: AddRefOptions): FileRef;
+declare function createFileRef(options: AddRefOptions): FileRef$1;
 /**
  * Remove a ref by ref_id (immutable)
  */
-declare function removeRefFromArray(refs: FileRef[], refId: string): FileRef[];
+declare function removeRefFromArray(refs: FileRef$1[], refId: string): FileRef$1[];
 /**
  * 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[];
+declare function removeRefsByCriteriaFromArray(refs: FileRef$1[], criteria: Omit<RemoveRefsCriteria, 'file_id' | 'scope_id'>): FileRef$1[];
 /**
  * Safely cast a FileMetadataRecord to FileMetadataRecordV2.
  * Missing V2 fields are defaulted.
@@ -3284,4 +3285,90 @@ declare function toV2Record(record: FileMetadataRecord): FileMetadataRecordV2;
  */
 declare function buildFileWithStatus(record: FileMetadataRecord): FileWithStatus;
 
-export { ALL_SYSTEM_VARIABLES, type AddExtractionOptions, type AddRefOptions, type AuthCallbacks, AuthenticationError, type CleanupOrphanedOptions, ConfigurationError, type ContentTagConfig, type CreateFolderOptions, type CrudServiceLike, DEFAULT_DATE_FORMATS, type DatabaseSchemaDefinition, type DatabaseTrackingConfig, DirectoryExistsError, DirectoryNotEmptyError, DirectoryNotFoundError, type DownloadOptions, DropboxAuth, type DropboxAuthCallbacks, type DropboxAuthConfig, type DropboxConfig, DropboxModule, type DropboxTokenData, 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_MIGRATION_V3, HAZO_FILES_NAMING_DEFAULT_TABLE_NAME, HAZO_FILES_NAMING_TABLE_SCHEMA, HAZO_FILES_TABLE_SCHEMA, type HazoFilesColumnDefinitions, type HazoFilesConfig, HazoFilesError, type HazoFilesMigrationV2, type HazoFilesMigrationV3, type HazoFilesNamingColumnDefinitions, type HazoFilesNamingTableSchema, type HazoFilesTableSchema, type HazoLLMInstance, InvalidExtensionError, InvalidPathError, LLMExtractionService, type LLMFactory, type LLMFactoryConfig, 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, createDropboxAuth, createDropboxModule, 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, getMigrationV3ForTable, 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, migrateToV3, normalizePath, parseConfig, parseFileData, parseFileRefs, parsePatternString, patternToString, recalculateMergedData, registerModule, removeExtractionById, removeExtractionByIndex, removeRefFromArray, removeRefsByCriteriaFromArray, sanitizeFilename, saveConfig, sortItems, stringifyFileData, stringifyFileRefs, successResult, toV2Record, updateExtractionById, validateExtractionData, validateFileDataStructure, validateNamingRuleSchema, validatePath };
+declare class NamingTemplate {
+    static render(template: string, vars: Record<string, unknown>): string;
+}
+
+type StoragePath = string;
+interface PutOpts {
+    /** Reject if the target path already exists (atomic). */
+    ifNotExists?: boolean;
+    /** Hint for content-type; provider may sniff if absent. */
+    contentType?: string;
+    /** Free-form key/value metadata persisted with the file when supported. */
+    metadata?: Record<string, string>;
+}
+interface PutResult {
+    /** Provider tag — `"app_file_server"`, `"gdrive"`, `"in_memory"`. */
+    provider: string;
+    /** Provider-native identifier (path for app-server; file ID for GDrive). */
+    native_id: string;
+    /** Size in bytes of the persisted body. */
+    size: number;
+}
+interface SignedUrlOpts {
+    /** Seconds the URL is valid for. */
+    ttl_seconds?: number;
+    /** Suggested download filename (Content-Disposition). */
+    filename_hint?: string;
+}
+interface ProbeResult {
+    ok: boolean;
+    /** Machine-readable error tag when ok=false. */
+    error?: "drive_not_shared" | "write_denied" | "invalid_id" | "transient" | "config_missing";
+    /** Free-form detail for logging. */
+    message?: string;
+}
+/**
+ * Storage provider abstraction. Every method MUST be idempotent at the
+ * data-content level — re-invoking put with identical body is allowed.
+ *
+ * Paths are logical; providers translate to native identifiers internally.
+ */
+interface FileStorageProvider {
+    put(path: StoragePath, body: Buffer | Readable, opts?: PutOpts): Promise<PutResult>;
+    get(path: StoragePath): Promise<Buffer | Readable>;
+    delete(path: StoragePath): Promise<void>;
+    exists(path: StoragePath): Promise<boolean>;
+    getSignedUrl(path: StoragePath, opts?: SignedUrlOpts): Promise<string>;
+    /** Used by validation cron + onboarding step 2. */
+    probe(): Promise<ProbeResult>;
+}
+
+interface WriteWithCollisionOpts {
+    provider: FileStorageProvider;
+    template: string;
+    vars: Record<string, unknown>;
+    body: Buffer;
+    /** Prefix to mount the rendered filename under, e.g. `"folders/abc123"`. */
+    path_prefix?: string;
+    /** Max attempts. Default 999. */
+    max_attempts?: number;
+    /** Extra opts passed to provider.put (ifNotExists is always forced true). */
+    put_opts?: Omit<PutOpts, "ifNotExists">;
+}
+declare function writeWithCollisionRetry(opts: WriteWithCollisionOpts): Promise<PutResult & {
+    logical_path: string;
+}>;
+
+interface FileRef {
+    ref_id: string;
+    ref_type: string;
+    ref_source: string;
+    form_id?: string;
+    field_id?: string;
+    message_id?: string;
+    document_id?: string;
+    created_at: string;
+    removed_at?: string;
+}
+interface FileWithRefs {
+    file_refs: FileRef[];
+    ref_count: number;
+}
+
+declare function addRef<T extends FileWithRefs>(file: T, ref: FileRef): T;
+declare function removeRef<T extends FileWithRefs>(file: T, ref_id: string, removed_at: string): T;
+declare function countRefs(file: Pick<FileWithRefs, "file_refs">): number;
+
+export { ALL_SYSTEM_VARIABLES, type AddExtractionOptions, type AddRefOptions, type AuthCallbacks, AuthenticationError, type CleanupOrphanedOptions, ConfigurationError, type ContentTagConfig, type CreateFolderOptions, type CrudServiceLike, DEFAULT_DATE_FORMATS, type DatabaseSchemaDefinition, type DatabaseTrackingConfig, DirectoryExistsError, DirectoryNotEmptyError, DirectoryNotFoundError, type DownloadOptions, DropboxAuth, type DropboxAuthCallbacks, type DropboxAuthConfig, type DropboxConfig, DropboxModule, type DropboxTokenData, 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$1 as FileRef, type FileRefVisibility, type FileStatus, type FileSystemItem, FileTooLargeError, type FileWithRefs, 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_MIGRATION_V3, HAZO_FILES_NAMING_DEFAULT_TABLE_NAME, HAZO_FILES_NAMING_TABLE_SCHEMA, HAZO_FILES_TABLE_SCHEMA, type HazoFilesColumnDefinitions, type HazoFilesConfig, HazoFilesError, type HazoFilesMigrationV2, type HazoFilesMigrationV3, type HazoFilesNamingColumnDefinitions, type HazoFilesNamingTableSchema, type HazoFilesTableSchema, type HazoLLMInstance, InvalidExtensionError, InvalidPathError, LLMExtractionService, type LLMFactory, type LLMFactoryConfig, 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, NamingTemplate, 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, type WriteWithCollisionOpts, addExtractionToFileData, addRef, backfillV2Defaults, buildFileWithStatus, clearExtractions, clonePattern, computeFileHash, computeFileHashFromStream, computeFileHashSync, computeFileInfo, countRefs, createAndInitializeModule, createDropboxAuth, createDropboxModule, 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, getMigrationV3ForTable, 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, migrateToV3, normalizePath, parseConfig, parseFileData, parseFileRefs, parsePatternString, patternToString, recalculateMergedData, registerModule, removeExtractionById, removeExtractionByIndex, removeRef, removeRefFromArray, removeRefsByCriteriaFromArray, sanitizeFilename, saveConfig, sortItems, stringifyFileData, stringifyFileRefs, successResult, toV2Record, updateExtractionById, validateExtractionData, validateFileDataStructure, validateNamingRuleSchema, validatePath, writeWithCollisionRetry };

package/dist/index.js

@@ -58,6 +58,7 @@ __export(index_exports, {
   LLMExtractionService: () => LLMExtractionService,
   LocalStorageModule: () => LocalStorageModule,
   NamingConventionService: () => NamingConventionService,
+  NamingTemplate: () => NamingTemplate,
   OperationError: () => OperationError,
   PermissionDeniedError: () => PermissionDeniedError,
   SYSTEM_COUNTER_VARIABLES: () => SYSTEM_COUNTER_VARIABLES,
@@ -66,6 +67,7 @@ __export(index_exports, {
   TrackedFileManager: () => TrackedFileManager,
   UploadExtractService: () => UploadExtractService,
   addExtractionToFileData: () => addExtractionToFileData,
+  addRef: () => addRef,
   backfillV2Defaults: () => backfillV2Defaults,
   buildFileWithStatus: () => buildFileWithStatus,
   clearExtractions: () => clearExtractions,
@@ -74,6 +76,7 @@ __export(index_exports, {
   computeFileHashFromStream: () => computeFileHashFromStream,
   computeFileHashSync: () => computeFileHashSync,
   computeFileInfo: () => computeFileInfo,
+  countRefs: () => countRefs,
   createAndInitializeModule: () => createAndInitializeModule,
   createDropboxAuth: () => createDropboxAuth,
   createDropboxModule: () => createDropboxModule,
@@ -164,6 +167,7 @@ __export(index_exports, {
   registerModule: () => registerModule,
   removeExtractionById: () => removeExtractionById,
   removeExtractionByIndex: () => removeExtractionByIndex,
+  removeRef: () => removeRef,
   removeRefFromArray: () => removeRefFromArray,
   removeRefsByCriteriaFromArray: () => removeRefsByCriteriaFromArray,
   sanitizeFilename: () => sanitizeFilename,
@@ -177,7 +181,8 @@ __export(index_exports, {
   validateExtractionData: () => validateExtractionData,
   validateFileDataStructure: () => validateFileDataStructure,
   validateNamingRuleSchema: () => validateNamingRuleSchema,
-  validatePath: () => validatePath
+  validatePath: () => validatePath,
+  writeWithCollisionRetry: () => writeWithCollisionRetry
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -6013,6 +6018,107 @@ async function migrateToV3(executor, dbType, tableName) {
     await executor.run(idx);
   }
 }
+
+// src/naming/template.ts
+var VAR_RE = /\{([a-zA-Z_][\w.]*)((?:\|[a-zA-Z_]+(?::[^}|]+)?)*)\}/g;
+var BAD_CHARS = /[/\\:*?"<>|]/g;
+var MAX_LEN = 200;
+var NamingTemplate = class {
+  static render(template, vars) {
+    const out = template.replace(VAR_RE, (_, name, pipes) => {
+      const value = resolveDottedPath(vars, name);
+      if (value === void 0) throw new Error(`missing variable: ${name}`);
+      let rendered = stringify2(value);
+      const formatters = pipes ? pipes.split("|").filter(Boolean) : [];
+      for (const f of formatters) {
+        const [fname, ...args] = f.split(":");
+        rendered = applyFormatter(fname, args.join(":"), rendered);
+      }
+      return rendered;
+    });
+    return out.replace(BAD_CHARS, "_").slice(0, MAX_LEN);
+  }
+};
+function resolveDottedPath(vars, path4) {
+  return path4.split(".").reduce((acc, key) => acc == null ? void 0 : acc[key], vars);
+}
+function stringify2(v) {
+  if (v == null) return "";
+  if (v instanceof Date) return v.toISOString();
+  return String(v);
+}
+function applyFormatter(name, arg, value) {
+  switch (name) {
+    case "slug":
+      return value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+    case "pad": {
+      const n = Number(arg);
+      if (!arg || isNaN(n)) throw new Error(`pad formatter requires a numeric arg, got: "${arg}"`);
+      return value.padStart(n, "0");
+    }
+    case "upper":
+      return value.toUpperCase();
+    case "lower":
+      return value.toLowerCase();
+    case "truncate": {
+      const n = Number(arg);
+      if (!arg || isNaN(n)) throw new Error(`truncate formatter requires a numeric arg, got: "${arg}"`);
+      return value.slice(0, n);
+    }
+    case "date": {
+      if (!value) throw new Error(`date formatter received empty value`);
+      const d = new Date(value);
+      if (isNaN(d.getTime())) throw new Error(`date formatter received invalid date: "${value}"`);
+      const pad2 = (n) => String(n).padStart(2, "0");
+      return arg.replace("YYYY", String(d.getUTCFullYear())).replace("MM", pad2(d.getUTCMonth() + 1)).replace("DD", pad2(d.getUTCDate())).replace("HH", pad2(d.getUTCHours())).replace("mm", pad2(d.getUTCMinutes())).replace("ss", pad2(d.getUTCSeconds()));
+    }
+    default:
+      throw new Error(`Unknown formatter: ${name}`);
+  }
+}
+
+// src/providers/types.ts
+var StorageCollisionExhausted = class extends Error {
+  constructor(attempts, lastPath) {
+    super(`Storage collision could not be resolved after ${attempts} attempts at "${lastPath}"`);
+    this.attempts = attempts;
+    this.lastPath = lastPath;
+    this.name = "StorageCollisionExhausted";
+  }
+};
+
+// src/naming/collision.ts
+async function writeWithCollisionRetry(opts) {
+  const max = opts.max_attempts ?? 999;
+  let lastPath = "";
+  for (let i = 1; i <= max; i++) {
+    const rendered = NamingTemplate.render(opts.template, { ...opts.vars, index: i });
+    const full = opts.path_prefix ? `${opts.path_prefix}/${rendered}` : rendered;
+    lastPath = full;
+    try {
+      const res = await opts.provider.put(full, opts.body, { ...opts.put_opts, ifNotExists: true });
+      return { ...res, logical_path: full };
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      if (!/exists/i.test(msg)) throw err;
+    }
+  }
+  throw new StorageCollisionExhausted(max, lastPath);
+}
+
+// src/reference-tracking/index.ts
+function addRef(file, ref) {
+  if (file.file_refs.some((r) => r.ref_id === ref.ref_id && !r.removed_at)) return file;
+  const next = [...file.file_refs, ref];
+  return { ...file, file_refs: next, ref_count: countRefs({ file_refs: next }) };
+}
+function removeRef(file, ref_id, removed_at) {
+  const next = file.file_refs.map((r) => r.ref_id === ref_id && !r.removed_at ? { ...r, removed_at } : r);
+  return { ...file, file_refs: next, ref_count: countRefs({ file_refs: next }) };
+}
+function countRefs(file) {
+  return file.file_refs.filter((r) => !r.removed_at).length;
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ALL_SYSTEM_VARIABLES,
@@ -6043,6 +6149,7 @@ async function migrateToV3(executor, dbType, tableName) {
   LLMExtractionService,
   LocalStorageModule,
   NamingConventionService,
+  NamingTemplate,
   OperationError,
   PermissionDeniedError,
   SYSTEM_COUNTER_VARIABLES,
@@ -6051,6 +6158,7 @@ async function migrateToV3(executor, dbType, tableName) {
   TrackedFileManager,
   UploadExtractService,
   addExtractionToFileData,
+  addRef,
   backfillV2Defaults,
   buildFileWithStatus,
   clearExtractions,
@@ -6059,6 +6167,7 @@ async function migrateToV3(executor, dbType, tableName) {
   computeFileHashFromStream,
   computeFileHashSync,
   computeFileInfo,
+  countRefs,
   createAndInitializeModule,
   createDropboxAuth,
   createDropboxModule,
@@ -6149,6 +6258,7 @@ async function migrateToV3(executor, dbType, tableName) {
   registerModule,
   removeExtractionById,
   removeExtractionByIndex,
+  removeRef,
   removeRefFromArray,
   removeRefsByCriteriaFromArray,
   sanitizeFilename,
@@ -6162,5 +6272,6 @@ async function migrateToV3(executor, dbType, tableName) {
   validateExtractionData,
   validateFileDataStructure,
   validateNamingRuleSchema,
-  validatePath
+  validatePath,
+  writeWithCollisionRetry
 });

package/dist/index.mjs

@@ -5830,6 +5830,107 @@ async function migrateToV3(executor, dbType, tableName) {
     await executor.run(idx);
   }
 }
+
+// src/naming/template.ts
+var VAR_RE = /\{([a-zA-Z_][\w.]*)((?:\|[a-zA-Z_]+(?::[^}|]+)?)*)\}/g;
+var BAD_CHARS = /[/\\:*?"<>|]/g;
+var MAX_LEN = 200;
+var NamingTemplate = class {
+  static render(template, vars) {
+    const out = template.replace(VAR_RE, (_, name, pipes) => {
+      const value = resolveDottedPath(vars, name);
+      if (value === void 0) throw new Error(`missing variable: ${name}`);
+      let rendered = stringify2(value);
+      const formatters = pipes ? pipes.split("|").filter(Boolean) : [];
+      for (const f of formatters) {
+        const [fname, ...args] = f.split(":");
+        rendered = applyFormatter(fname, args.join(":"), rendered);
+      }
+      return rendered;
+    });
+    return out.replace(BAD_CHARS, "_").slice(0, MAX_LEN);
+  }
+};
+function resolveDottedPath(vars, path4) {
+  return path4.split(".").reduce((acc, key) => acc == null ? void 0 : acc[key], vars);
+}
+function stringify2(v) {
+  if (v == null) return "";
+  if (v instanceof Date) return v.toISOString();
+  return String(v);
+}
+function applyFormatter(name, arg, value) {
+  switch (name) {
+    case "slug":
+      return value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+    case "pad": {
+      const n = Number(arg);
+      if (!arg || isNaN(n)) throw new Error(`pad formatter requires a numeric arg, got: "${arg}"`);
+      return value.padStart(n, "0");
+    }
+    case "upper":
+      return value.toUpperCase();
+    case "lower":
+      return value.toLowerCase();
+    case "truncate": {
+      const n = Number(arg);
+      if (!arg || isNaN(n)) throw new Error(`truncate formatter requires a numeric arg, got: "${arg}"`);
+      return value.slice(0, n);
+    }
+    case "date": {
+      if (!value) throw new Error(`date formatter received empty value`);
+      const d = new Date(value);
+      if (isNaN(d.getTime())) throw new Error(`date formatter received invalid date: "${value}"`);
+      const pad2 = (n) => String(n).padStart(2, "0");
+      return arg.replace("YYYY", String(d.getUTCFullYear())).replace("MM", pad2(d.getUTCMonth() + 1)).replace("DD", pad2(d.getUTCDate())).replace("HH", pad2(d.getUTCHours())).replace("mm", pad2(d.getUTCMinutes())).replace("ss", pad2(d.getUTCSeconds()));
+    }
+    default:
+      throw new Error(`Unknown formatter: ${name}`);
+  }
+}
+
+// src/providers/types.ts
+var StorageCollisionExhausted = class extends Error {
+  constructor(attempts, lastPath) {
+    super(`Storage collision could not be resolved after ${attempts} attempts at "${lastPath}"`);
+    this.attempts = attempts;
+    this.lastPath = lastPath;
+    this.name = "StorageCollisionExhausted";
+  }
+};
+
+// src/naming/collision.ts
+async function writeWithCollisionRetry(opts) {
+  const max = opts.max_attempts ?? 999;
+  let lastPath = "";
+  for (let i = 1; i <= max; i++) {
+    const rendered = NamingTemplate.render(opts.template, { ...opts.vars, index: i });
+    const full = opts.path_prefix ? `${opts.path_prefix}/${rendered}` : rendered;
+    lastPath = full;
+    try {
+      const res = await opts.provider.put(full, opts.body, { ...opts.put_opts, ifNotExists: true });
+      return { ...res, logical_path: full };
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      if (!/exists/i.test(msg)) throw err;
+    }
+  }
+  throw new StorageCollisionExhausted(max, lastPath);
+}
+
+// src/reference-tracking/index.ts
+function addRef(file, ref) {
+  if (file.file_refs.some((r) => r.ref_id === ref.ref_id && !r.removed_at)) return file;
+  const next = [...file.file_refs, ref];
+  return { ...file, file_refs: next, ref_count: countRefs({ file_refs: next }) };
+}
+function removeRef(file, ref_id, removed_at) {
+  const next = file.file_refs.map((r) => r.ref_id === ref_id && !r.removed_at ? { ...r, removed_at } : r);
+  return { ...file, file_refs: next, ref_count: countRefs({ file_refs: next }) };
+}
+function countRefs(file) {
+  return file.file_refs.filter((r) => !r.removed_at).length;
+}
 export {
   ALL_SYSTEM_VARIABLES,
   AuthenticationError,
@@ -5859,6 +5960,7 @@ export {
   LLMExtractionService,
   LocalStorageModule,
   NamingConventionService,
+  NamingTemplate,
   OperationError,
   PermissionDeniedError,
   SYSTEM_COUNTER_VARIABLES,
@@ -5867,6 +5969,7 @@ export {
   TrackedFileManager,
   UploadExtractService,
   addExtractionToFileData,
+  addRef,
   backfillV2Defaults,
   buildFileWithStatus,
   clearExtractions,
@@ -5875,6 +5978,7 @@ export {
   computeFileHashFromStream,
   computeFileHashSync,
   computeFileInfo,
+  countRefs,
   createAndInitializeModule,
   createDropboxAuth,
   createDropboxModule,
@@ -5965,6 +6069,7 @@ export {
   registerModule,
   removeExtractionById,
   removeExtractionByIndex,
+  removeRef,
   removeRefFromArray,
   removeRefsByCriteriaFromArray,
   sanitizeFilename,
@@ -5978,5 +6083,6 @@ export {
   validateExtractionData,
   validateFileDataStructure,
   validateNamingRuleSchema,
-  validatePath
+  validatePath,
+  writeWithCollisionRetry
 };

package/dist/server/index.d.mts

@@ -2665,6 +2665,49 @@ declare class AppFileServerProvider implements FileStorageProvider {
     probe(): Promise<ProbeResult>;
 }
 
+declare class InMemoryProvider implements FileStorageProvider {
+    readonly provider_tag: "in_memory";
+    private readonly store;
+    put(path: string, body: Buffer | Readable, opts?: PutOpts): Promise<PutResult>;
+    get(path: string): Promise<Buffer>;
+    delete(path: string): Promise<void>;
+    exists(path: string): Promise<boolean>;
+    getSignedUrl(path: string, _opts?: SignedUrlOpts): Promise<string>;
+    probe(): Promise<ProbeResult>;
+    /** Test-only escape hatch — exposes the internal store for assertions. */
+    snapshot(): Map<string, Buffer>;
+}
+
+interface DrivePathCache {
+    lookup(key: string): Promise<string | null>;
+    write(key: string, folder_id: string): Promise<void>;
+    invalidate(key: string): Promise<void>;
+}
+interface GoogleDriveOpts {
+    /** Raw JSON keyfile contents (decoded from GOOGLE_SERVICE_ACCOUNT_JSON env var). */
+    service_account_json: string;
+    /** Target Shared Drive ID. */
+    shared_drive_id: string;
+    /** Lazy folder-ID cache, scoped per Hazodocs org. */
+    path_cache: DrivePathCache;
+}
+declare class GoogleDriveProvider implements FileStorageProvider {
+    readonly provider_tag: "gdrive";
+    private readonly drive;
+    private readonly driveId;
+    private readonly cache;
+    constructor(opts: GoogleDriveOpts);
+    probe(): Promise<ProbeResult>;
+    put(path: string, body: Buffer | Readable, opts?: PutOpts): Promise<PutResult>;
+    get(path: string): Promise<Buffer>;
+    delete(path: string): Promise<void>;
+    exists(path: string): Promise<boolean>;
+    getSignedUrl(path: string, _opts?: SignedUrlOpts): Promise<string>;
+    private resolvePath;
+    private findChild;
+    private lookupFileId;
+}
+
 /**
  * Migration: Add Reference Tracking (V2)
  *
@@ -3728,4 +3771,4 @@ declare function toV2Record(record: FileMetadataRecord): FileMetadataRecordV2;
  */
 declare function buildFileWithStatus(record: FileMetadataRecord): FileWithStatus;
 
-export { ALL_SYSTEM_VARIABLES, type AddExtractionOptions, type AddRefOptions, type AppFileServerOpts, AppFileServerProvider, type AuthCallbacks, AuthenticationError, type CleanupOrphanedOptions, ConfigurationError, type ContentTagConfig, type CreateFolderOptions, type CrudServiceLike, DEFAULT_DATE_FORMATS, type DatabaseSchemaDefinition, type DatabaseTrackingConfig, DirectoryExistsError, DirectoryNotEmptyError, DirectoryNotFoundError, type DownloadOptions, DropboxAuth, type DropboxAuthCallbacks, type DropboxAuthConfig, type DropboxConfig, DropboxModule, type DropboxTokenData, 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 FileStorageProvider, type FileSystemItem, FileTooLargeError, type FileWithStatus, type FindOrphanedOptions, type FolderItem, type GeneratedNameResult, type GoogleAuthConfig, GoogleDriveAuth, type GoogleDriveConfig, GoogleDriveModule, HAZO_FILES_DEFAULT_TABLE_NAME, HAZO_FILES_JOB_TYPES, HAZO_FILES_MIGRATION_V2, HAZO_FILES_MIGRATION_V3, HAZO_FILES_MIGRATION_V4, HAZO_FILES_NAMING_DEFAULT_TABLE_NAME, HAZO_FILES_NAMING_TABLE_SCHEMA, HAZO_FILES_TABLE_SCHEMA, HAZO_FILE_QUOTAS_DEFAULT_TABLE_NAME, HAZO_FILE_QUOTAS_TABLE_SCHEMA, type HazoFileQuotasColumnDefinitions, type HazoFilesColumnDefinitions, type HazoFilesConfig, HazoFilesError, type HazoFilesJobType, type HazoFilesMigrationV2, type HazoFilesMigrationV3, type HazoFilesMigrationV4, type HazoFilesNamingColumnDefinitions, type HazoFilesNamingTableSchema, type HazoFilesServerInstance, type HazoFilesServerOptions, type HazoFilesTableSchema, type HazoLLMInstance, type HazoLogger, ImportSizeCapError, InvalidExtensionError, InvalidPathError, LLMExtractionService, type LLMFactory, type LLMFactoryConfig, 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 ProbeResult, type ProgressCallback, type PurgeJobHandlerOptions, type PurgeOnePayload, type PurgePlanPayload, type PurgePlanResult, type PutOpts, type PutResult, type QuotaCrudServiceLike, QuotaExceededError, QuotaService, type QuotaServiceOptions, type QuotaStatus, type QuotaThresholdEvent, type RemoveExtractionOptions, type RemoveRefsCriteria, type RenameOptions, SSRFError, SYSTEM_COUNTER_VARIABLES, SYSTEM_DATE_VARIABLES, SYSTEM_FILE_VARIABLES, type SignedUrlOpts, StorageCollisionExhausted, type StorageModule, StorageNotConfigured, type StoragePath, type StorageProvider, StorageUnavailable, 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, createBasicFileManager, createDropboxAuth, createDropboxModule, createEmptyFileDataStructure, createEmptyNamingRuleSchema, createFileItem, createFileManager, createFileMetadataService, createFileRef, createFolderItem, createGoogleDriveAuth, createGoogleDriveModule, createHazoFilesServer, createInitializedFileManager, createInitializedTrackedFileManager, createLLMExtractionService, createLiteralSegment, createLocalModule, createModule, createNamingConventionService, createPurgeJobHandlers, createQuotaService, 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, getMigrationV3ForTable, getMigrationV4ForTable, 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, migrateToV3, normalizePath, parseConfig, parseFileData, parseFileRefs, parsePatternString, patternToString, recalculateMergedData, registerModule, removeExtractionById, removeExtractionByIndex, removeRefFromArray, removeRefsByCriteriaFromArray, sanitizeFilename, saveConfig, sortItems, stringifyFileData, stringifyFileRefs, successResult, toV2Record, updateExtractionById, validateExtractionData, validateFileDataStructure, validateNamingRuleSchema, validatePath };
+export { ALL_SYSTEM_VARIABLES, type AddExtractionOptions, type AddRefOptions, type AppFileServerOpts, AppFileServerProvider, type AuthCallbacks, AuthenticationError, type CleanupOrphanedOptions, ConfigurationError, type ContentTagConfig, type CreateFolderOptions, type CrudServiceLike, DEFAULT_DATE_FORMATS, type DatabaseSchemaDefinition, type DatabaseTrackingConfig, DirectoryExistsError, DirectoryNotEmptyError, DirectoryNotFoundError, type DownloadOptions, type DrivePathCache, DropboxAuth, type DropboxAuthCallbacks, type DropboxAuthConfig, type DropboxConfig, DropboxModule, type DropboxTokenData, 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 FileStorageProvider, type FileSystemItem, FileTooLargeError, type FileWithStatus, type FindOrphanedOptions, type FolderItem, type GeneratedNameResult, type GoogleAuthConfig, GoogleDriveAuth, type GoogleDriveConfig, GoogleDriveModule, type GoogleDriveOpts, GoogleDriveProvider, HAZO_FILES_DEFAULT_TABLE_NAME, HAZO_FILES_JOB_TYPES, HAZO_FILES_MIGRATION_V2, HAZO_FILES_MIGRATION_V3, HAZO_FILES_MIGRATION_V4, HAZO_FILES_NAMING_DEFAULT_TABLE_NAME, HAZO_FILES_NAMING_TABLE_SCHEMA, HAZO_FILES_TABLE_SCHEMA, HAZO_FILE_QUOTAS_DEFAULT_TABLE_NAME, HAZO_FILE_QUOTAS_TABLE_SCHEMA, type HazoFileQuotasColumnDefinitions, type HazoFilesColumnDefinitions, type HazoFilesConfig, HazoFilesError, type HazoFilesJobType, type HazoFilesMigrationV2, type HazoFilesMigrationV3, type HazoFilesMigrationV4, type HazoFilesNamingColumnDefinitions, type HazoFilesNamingTableSchema, type HazoFilesServerInstance, type HazoFilesServerOptions, type HazoFilesTableSchema, type HazoLLMInstance, type HazoLogger, ImportSizeCapError, InMemoryProvider, InvalidExtensionError, InvalidPathError, LLMExtractionService, type LLMFactory, type LLMFactoryConfig, 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 ProbeResult, type ProgressCallback, type PurgeJobHandlerOptions, type PurgeOnePayload, type PurgePlanPayload, type PurgePlanResult, type PutOpts, type PutResult, type QuotaCrudServiceLike, QuotaExceededError, QuotaService, type QuotaServiceOptions, type QuotaStatus, type QuotaThresholdEvent, type RemoveExtractionOptions, type RemoveRefsCriteria, type RenameOptions, SSRFError, SYSTEM_COUNTER_VARIABLES, SYSTEM_DATE_VARIABLES, SYSTEM_FILE_VARIABLES, type SignedUrlOpts, StorageCollisionExhausted, type StorageModule, StorageNotConfigured, type StoragePath, type StorageProvider, StorageUnavailable, 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, createBasicFileManager, createDropboxAuth, createDropboxModule, createEmptyFileDataStructure, createEmptyNamingRuleSchema, createFileItem, createFileManager, createFileMetadataService, createFileRef, createFolderItem, createGoogleDriveAuth, createGoogleDriveModule, createHazoFilesServer, createInitializedFileManager, createInitializedTrackedFileManager, createLLMExtractionService, createLiteralSegment, createLocalModule, createModule, createNamingConventionService, createPurgeJobHandlers, createQuotaService, 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, getMigrationV3ForTable, getMigrationV4ForTable, 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, migrateToV3, normalizePath, parseConfig, parseFileData, parseFileRefs, parsePatternString, patternToString, recalculateMergedData, registerModule, removeExtractionById, removeExtractionByIndex, removeRefFromArray, removeRefsByCriteriaFromArray, sanitizeFilename, saveConfig, sortItems, stringifyFileData, stringifyFileRefs, successResult, toV2Record, updateExtractionById, validateExtractionData, validateFileDataStructure, validateNamingRuleSchema, validatePath };

package/dist/server/index.d.ts

@@ -2665,6 +2665,49 @@ declare class AppFileServerProvider implements FileStorageProvider {
     probe(): Promise<ProbeResult>;
 }
 
+declare class InMemoryProvider implements FileStorageProvider {
+    readonly provider_tag: "in_memory";
+    private readonly store;
+    put(path: string, body: Buffer | Readable, opts?: PutOpts): Promise<PutResult>;
+    get(path: string): Promise<Buffer>;
+    delete(path: string): Promise<void>;
+    exists(path: string): Promise<boolean>;
+    getSignedUrl(path: string, _opts?: SignedUrlOpts): Promise<string>;
+    probe(): Promise<ProbeResult>;
+    /** Test-only escape hatch — exposes the internal store for assertions. */
+    snapshot(): Map<string, Buffer>;
+}
+
+interface DrivePathCache {
+    lookup(key: string): Promise<string | null>;
+    write(key: string, folder_id: string): Promise<void>;
+    invalidate(key: string): Promise<void>;
+}
+interface GoogleDriveOpts {
+    /** Raw JSON keyfile contents (decoded from GOOGLE_SERVICE_ACCOUNT_JSON env var). */
+    service_account_json: string;
+    /** Target Shared Drive ID. */
+    shared_drive_id: string;
+    /** Lazy folder-ID cache, scoped per Hazodocs org. */
+    path_cache: DrivePathCache;
+}
+declare class GoogleDriveProvider implements FileStorageProvider {
+    readonly provider_tag: "gdrive";
+    private readonly drive;
+    private readonly driveId;
+    private readonly cache;
+    constructor(opts: GoogleDriveOpts);
+    probe(): Promise<ProbeResult>;
+    put(path: string, body: Buffer | Readable, opts?: PutOpts): Promise<PutResult>;
+    get(path: string): Promise<Buffer>;
+    delete(path: string): Promise<void>;
+    exists(path: string): Promise<boolean>;
+    getSignedUrl(path: string, _opts?: SignedUrlOpts): Promise<string>;
+    private resolvePath;
+    private findChild;
+    private lookupFileId;
+}
+
 /**
  * Migration: Add Reference Tracking (V2)
  *
@@ -3728,4 +3771,4 @@ declare function toV2Record(record: FileMetadataRecord): FileMetadataRecordV2;
  */
 declare function buildFileWithStatus(record: FileMetadataRecord): FileWithStatus;
 
-export { ALL_SYSTEM_VARIABLES, type AddExtractionOptions, type AddRefOptions, type AppFileServerOpts, AppFileServerProvider, type AuthCallbacks, AuthenticationError, type CleanupOrphanedOptions, ConfigurationError, type ContentTagConfig, type CreateFolderOptions, type CrudServiceLike, DEFAULT_DATE_FORMATS, type DatabaseSchemaDefinition, type DatabaseTrackingConfig, DirectoryExistsError, DirectoryNotEmptyError, DirectoryNotFoundError, type DownloadOptions, DropboxAuth, type DropboxAuthCallbacks, type DropboxAuthConfig, type DropboxConfig, DropboxModule, type DropboxTokenData, 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 FileStorageProvider, type FileSystemItem, FileTooLargeError, type FileWithStatus, type FindOrphanedOptions, type FolderItem, type GeneratedNameResult, type GoogleAuthConfig, GoogleDriveAuth, type GoogleDriveConfig, GoogleDriveModule, HAZO_FILES_DEFAULT_TABLE_NAME, HAZO_FILES_JOB_TYPES, HAZO_FILES_MIGRATION_V2, HAZO_FILES_MIGRATION_V3, HAZO_FILES_MIGRATION_V4, HAZO_FILES_NAMING_DEFAULT_TABLE_NAME, HAZO_FILES_NAMING_TABLE_SCHEMA, HAZO_FILES_TABLE_SCHEMA, HAZO_FILE_QUOTAS_DEFAULT_TABLE_NAME, HAZO_FILE_QUOTAS_TABLE_SCHEMA, type HazoFileQuotasColumnDefinitions, type HazoFilesColumnDefinitions, type HazoFilesConfig, HazoFilesError, type HazoFilesJobType, type HazoFilesMigrationV2, type HazoFilesMigrationV3, type HazoFilesMigrationV4, type HazoFilesNamingColumnDefinitions, type HazoFilesNamingTableSchema, type HazoFilesServerInstance, type HazoFilesServerOptions, type HazoFilesTableSchema, type HazoLLMInstance, type HazoLogger, ImportSizeCapError, InvalidExtensionError, InvalidPathError, LLMExtractionService, type LLMFactory, type LLMFactoryConfig, 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 ProbeResult, type ProgressCallback, type PurgeJobHandlerOptions, type PurgeOnePayload, type PurgePlanPayload, type PurgePlanResult, type PutOpts, type PutResult, type QuotaCrudServiceLike, QuotaExceededError, QuotaService, type QuotaServiceOptions, type QuotaStatus, type QuotaThresholdEvent, type RemoveExtractionOptions, type RemoveRefsCriteria, type RenameOptions, SSRFError, SYSTEM_COUNTER_VARIABLES, SYSTEM_DATE_VARIABLES, SYSTEM_FILE_VARIABLES, type SignedUrlOpts, StorageCollisionExhausted, type StorageModule, StorageNotConfigured, type StoragePath, type StorageProvider, StorageUnavailable, 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, createBasicFileManager, createDropboxAuth, createDropboxModule, createEmptyFileDataStructure, createEmptyNamingRuleSchema, createFileItem, createFileManager, createFileMetadataService, createFileRef, createFolderItem, createGoogleDriveAuth, createGoogleDriveModule, createHazoFilesServer, createInitializedFileManager, createInitializedTrackedFileManager, createLLMExtractionService, createLiteralSegment, createLocalModule, createModule, createNamingConventionService, createPurgeJobHandlers, createQuotaService, 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, getMigrationV3ForTable, getMigrationV4ForTable, 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, migrateToV3, normalizePath, parseConfig, parseFileData, parseFileRefs, parsePatternString, patternToString, recalculateMergedData, registerModule, removeExtractionById, removeExtractionByIndex, removeRefFromArray, removeRefsByCriteriaFromArray, sanitizeFilename, saveConfig, sortItems, stringifyFileData, stringifyFileRefs, successResult, toV2Record, updateExtractionById, validateExtractionData, validateFileDataStructure, validateNamingRuleSchema, validatePath };
+export { ALL_SYSTEM_VARIABLES, type AddExtractionOptions, type AddRefOptions, type AppFileServerOpts, AppFileServerProvider, type AuthCallbacks, AuthenticationError, type CleanupOrphanedOptions, ConfigurationError, type ContentTagConfig, type CreateFolderOptions, type CrudServiceLike, DEFAULT_DATE_FORMATS, type DatabaseSchemaDefinition, type DatabaseTrackingConfig, DirectoryExistsError, DirectoryNotEmptyError, DirectoryNotFoundError, type DownloadOptions, type DrivePathCache, DropboxAuth, type DropboxAuthCallbacks, type DropboxAuthConfig, type DropboxConfig, DropboxModule, type DropboxTokenData, 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 FileStorageProvider, type FileSystemItem, FileTooLargeError, type FileWithStatus, type FindOrphanedOptions, type FolderItem, type GeneratedNameResult, type GoogleAuthConfig, GoogleDriveAuth, type GoogleDriveConfig, GoogleDriveModule, type GoogleDriveOpts, GoogleDriveProvider, HAZO_FILES_DEFAULT_TABLE_NAME, HAZO_FILES_JOB_TYPES, HAZO_FILES_MIGRATION_V2, HAZO_FILES_MIGRATION_V3, HAZO_FILES_MIGRATION_V4, HAZO_FILES_NAMING_DEFAULT_TABLE_NAME, HAZO_FILES_NAMING_TABLE_SCHEMA, HAZO_FILES_TABLE_SCHEMA, HAZO_FILE_QUOTAS_DEFAULT_TABLE_NAME, HAZO_FILE_QUOTAS_TABLE_SCHEMA, type HazoFileQuotasColumnDefinitions, type HazoFilesColumnDefinitions, type HazoFilesConfig, HazoFilesError, type HazoFilesJobType, type HazoFilesMigrationV2, type HazoFilesMigrationV3, type HazoFilesMigrationV4, type HazoFilesNamingColumnDefinitions, type HazoFilesNamingTableSchema, type HazoFilesServerInstance, type HazoFilesServerOptions, type HazoFilesTableSchema, type HazoLLMInstance, type HazoLogger, ImportSizeCapError, InMemoryProvider, InvalidExtensionError, InvalidPathError, LLMExtractionService, type LLMFactory, type LLMFactoryConfig, 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 ProbeResult, type ProgressCallback, type PurgeJobHandlerOptions, type PurgeOnePayload, type PurgePlanPayload, type PurgePlanResult, type PutOpts, type PutResult, type QuotaCrudServiceLike, QuotaExceededError, QuotaService, type QuotaServiceOptions, type QuotaStatus, type QuotaThresholdEvent, type RemoveExtractionOptions, type RemoveRefsCriteria, type RenameOptions, SSRFError, SYSTEM_COUNTER_VARIABLES, SYSTEM_DATE_VARIABLES, SYSTEM_FILE_VARIABLES, type SignedUrlOpts, StorageCollisionExhausted, type StorageModule, StorageNotConfigured, type StoragePath, type StorageProvider, StorageUnavailable, 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, createBasicFileManager, createDropboxAuth, createDropboxModule, createEmptyFileDataStructure, createEmptyNamingRuleSchema, createFileItem, createFileManager, createFileMetadataService, createFileRef, createFolderItem, createGoogleDriveAuth, createGoogleDriveModule, createHazoFilesServer, createInitializedFileManager, createInitializedTrackedFileManager, createLLMExtractionService, createLiteralSegment, createLocalModule, createModule, createNamingConventionService, createPurgeJobHandlers, createQuotaService, 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, getMigrationV3ForTable, getMigrationV4ForTable, 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, migrateToV3, normalizePath, parseConfig, parseFileData, parseFileRefs, parsePatternString, patternToString, recalculateMergedData, registerModule, removeExtractionById, removeExtractionByIndex, removeRefFromArray, removeRefsByCriteriaFromArray, sanitizeFilename, saveConfig, sortItems, stringifyFileData, stringifyFileRefs, successResult, toV2Record, updateExtractionById, validateExtractionData, validateFileDataStructure, validateNamingRuleSchema, validatePath };