hazo_files 1.4.3 → 1.4.4

package/README.md

@@ -7,7 +7,7 @@ A powerful, modular file management package for Node.js and React applications w
 
 ## Features
 
-- **Multiple Storage Providers**: Local filesystem and Google Drive support out of the box
+- **Multiple Storage Providers**: Local filesystem, Google Drive, and Dropbox support out of the box
 - **Modular Architecture**: Easily add custom storage providers
 - **Unified API**: Single consistent interface across all storage providers
 - **React UI Components**: Drop-in FileBrowser component with folder tree, file list, and preview
@@ -21,7 +21,8 @@ A powerful, modular file management package for Node.js and React applications w
 - **Content Tagging**: Optional LLM-based content classification at upload time or on-demand via `content_tag` field
 - **Schema Migrations**: Built-in V2/V3 migration utilities for adding reference tracking and content tagging to existing databases
 - **TypeScript**: Full type safety and IntelliSense support
-- **OAuth Integration**: Built-in Google Drive OAuth authentication
+- **OAuth Integration**: Built-in Google Drive and Dropbox OAuth authentication
+- **Prompt Cache Invalidation**: Passthrough for hazo_llm_api prompt cache management via server instance
 - **Progress Tracking**: Upload/download progress callbacks
 - **File Validation**: Extension filtering and file size limits
 - **Error Handling**: Comprehensive error types and handling
@@ -1173,7 +1174,10 @@ const folderResult = await uploadExtract.createFolderFromConvention(
 ```typescript
 import { LLMExtractionService } from 'hazo_files';
 
-const extractionService = new LLMExtractionService(llmFactory, 'gemini');
+const extractionService = new LLMExtractionService({
+  create: llmFactory,
+  invalidateCache: (area, key) => invalidate_prompt_cache(area, key), // optional
+}, 'gemini');
 
 // Extract from document
 const result = await extractionService.extractFromDocument(
@@ -1409,7 +1413,10 @@ const hazoFiles = await createHazoFilesServer({
     local: { basePath: './storage' },
   },
   enableTracking: true,
-  llmFactory: (provider) => createLLM({ provider }),
+  llmFactory: {
+    create: (provider) => createLLM({ provider }),
+    invalidateCache: (area, key) => invalidate_prompt_cache(area, key), // optional
+  },
   // Optional: enable automatic content tagging for all uploads
   defaultContentTagConfig: {
     content_tag_set_by_llm: true,
@@ -1420,7 +1427,10 @@ const hazoFiles = await createHazoFilesServer({
 });
 
 // Access all services
-const { fileManager, metadataService, namingService, extractionService, uploadExtractService } = hazoFiles;
+const { fileManager, metadataService, namingService, extractionService, uploadExtractService, invalidatePromptCache } = hazoFiles;
+
+// Invalidate prompt cache without importing hazo_llm_api directly
+invalidatePromptCache?.('classification', 'classify_document');
 ```
 
 ## API Reference

package/dist/index.d.mts

@@ -514,7 +514,7 @@ interface UploadWithRefOptions {
  * Core types for the hazo_files package
  */
 /** Supported storage provider types */
-type StorageProvider = 'local' | 'google_drive';
+type StorageProvider = 'local' | 'google_drive' | 'dropbox';
 /** File item representing a file in storage */
 interface FileItem {
     id: string;
@@ -542,11 +542,21 @@ interface FolderItem {
 }
 /** Union type for file system items */
 type FileSystemItem = FileItem | FolderItem;
+/** Dropbox specific configuration */
+interface DropboxConfig {
+    clientId: string;
+    clientSecret: string;
+    redirectUri: string;
+    refreshToken?: string;
+    accessToken?: string;
+    rootPath?: string;
+}
 /** Configuration for the file manager */
 interface HazoFilesConfig {
     provider: StorageProvider;
     local?: LocalStorageConfig;
     google_drive?: GoogleDriveConfig;
+    dropbox?: DropboxConfig;
 }
 /** Local storage specific configuration */
 interface LocalStorageConfig {
@@ -1429,6 +1439,13 @@ interface HazoLLMInstance {
  * Factory function type for creating LLM instances
  */
 type LLMFactory = (provider: LLMProvider, options?: Record<string, unknown>) => HazoLLMInstance | Promise<HazoLLMInstance>;
+/**
+ * Extended LLM factory configuration with optional cache management
+ */
+interface LLMFactoryConfig {
+    create: LLMFactory;
+    invalidateCache?: (area?: string, key?: string) => void;
+}
 /**
  * LLM Extraction Service
  *
@@ -1470,7 +1487,13 @@ type LLMFactory = (provider: LLMProvider, options?: Record<string, unknown>) =>
 declare class LLMExtractionService {
     private llmFactory;
     private defaultProvider;
-    constructor(llmFactory: LLMFactory, defaultProvider?: LLMProvider);
+    private cacheInvalidator?;
+    constructor(factoryConfig: LLMFactoryConfig, defaultProvider?: LLMProvider);
+    /**
+     * Invalidate the LLM prompt cache
+     * Passthrough to hazo_llm_api's invalidate_prompt_cache when configured
+     */
+    invalidatePromptCache(area?: string, key?: string): void;
     /**
      * Extract data from a document
      *
@@ -1502,10 +1525,10 @@ declare class LLMExtractionService {
 /**
  * Create an LLMExtractionService instance
  *
- * @param llmFactory - Factory function for creating LLM instances
+ * @param factoryConfig - LLM factory configuration with create function and optional cache invalidation
  * @param defaultProvider - Default LLM provider (default: 'gemini')
  */
-declare function createLLMExtractionService(llmFactory: LLMFactory, defaultProvider?: LLMProvider): LLMExtractionService;
+declare function createLLMExtractionService(factoryConfig: LLMFactoryConfig, defaultProvider?: LLMProvider): LLMExtractionService;
 
 /**
  * Upload + Extract Service
@@ -2449,6 +2472,150 @@ declare class GoogleDriveModule extends BaseStorageModule {
  */
 declare function createGoogleDriveModule(): GoogleDriveModule;
 
+/**
+ * Dropbox OAuth Authentication Handler
+ * Manages OAuth flow, token storage, and token refresh
+ */
+interface DropboxAuthConfig {
+    clientId: string;
+    clientSecret: string;
+    redirectUri: string;
+}
+interface DropboxTokenData {
+    accessToken: string;
+    refreshToken: string;
+    expiryDate?: number;
+}
+interface DropboxAuthCallbacks {
+    onTokensUpdated?: (tokens: DropboxTokenData) => Promise<void>;
+    getStoredTokens?: () => Promise<DropboxTokenData | null>;
+}
+/**
+ * Dropbox Authentication Manager
+ */
+declare class DropboxAuth {
+    private config;
+    private callbacks;
+    private tokens;
+    constructor(config: DropboxAuthConfig, callbacks?: DropboxAuthCallbacks);
+    /**
+     * Generate the authorization URL for OAuth consent
+     */
+    getAuthUrl(state?: string): string;
+    /**
+     * Exchange authorization code for tokens
+     */
+    exchangeCodeForTokens(code: string): Promise<DropboxTokenData>;
+    /**
+     * Set tokens directly (e.g., from stored tokens)
+     */
+    setTokens(tokens: DropboxTokenData): Promise<void>;
+    /**
+     * Load tokens from storage using callback
+     */
+    loadStoredTokens(): Promise<boolean>;
+    /**
+     * Check if authenticated
+     */
+    isAuthenticated(): boolean;
+    /**
+     * Get current tokens
+     */
+    getTokens(): DropboxTokenData | null;
+    /**
+     * Get current access token
+     */
+    getAccessToken(): string | null;
+    /**
+     * Refresh the access token
+     */
+    refreshAccessToken(): Promise<DropboxTokenData>;
+    /**
+     * Revoke access (disconnect)
+     */
+    revokeAccess(): Promise<void>;
+    /**
+     * Check if token is expired or will expire soon
+     */
+    isTokenExpired(bufferSeconds?: number): boolean;
+    /**
+     * Ensure valid access token (refresh if needed)
+     */
+    ensureValidToken(): Promise<void>;
+}
+/**
+ * Create a new DropboxAuth instance
+ */
+declare function createDropboxAuth(config: DropboxAuthConfig, callbacks?: DropboxAuthCallbacks): DropboxAuth;
+
+/**
+ * Dropbox Storage Module
+ * Implements file operations using Dropbox API via the official SDK
+ */
+
+declare class DropboxModule extends BaseStorageModule {
+    readonly provider: StorageProvider;
+    private auth;
+    private dbx;
+    private rootPath;
+    private authCallbacks;
+    /**
+     * Set authentication callbacks for token persistence
+     */
+    setAuthCallbacks(callbacks: DropboxAuthCallbacks): void;
+    initialize(config: HazoFilesConfig): Promise<void>;
+    /**
+     * Create/recreate the Dropbox SDK client with the current access token
+     */
+    private createDropboxClient;
+    /**
+     * Get the auth instance for OAuth flow
+     */
+    getAuth(): DropboxAuth;
+    /**
+     * Check if user is authenticated
+     */
+    isAuthenticated(): boolean;
+    /**
+     * Authenticate with provided tokens
+     */
+    authenticate(tokens: DropboxTokenData): Promise<void>;
+    /**
+     * Ensure authenticated before operations
+     */
+    private ensureAuthenticated;
+    /**
+     * Convert virtual path to Dropbox path
+     * Virtual: /folder/file.txt -> Dropbox: /folder/file.txt (or /rootPath/folder/file.txt)
+     * Dropbox root is empty string "", not "/"
+     */
+    private toDropboxPath;
+    /**
+     * Convert Dropbox metadata to FileSystemItem
+     */
+    private metadataToItem;
+    /**
+     * Convert a Dropbox path_display to virtual path
+     */
+    private toVirtualPath;
+    createDirectory(virtualPath: string): Promise<OperationResult<FolderItem>>;
+    removeDirectory(virtualPath: string, recursive?: boolean): Promise<OperationResult>;
+    uploadFile(source: string | Buffer | ReadableStream, remotePath: string, options?: UploadOptions): Promise<OperationResult<FileItem>>;
+    downloadFile(remotePath: string, localPath?: string, options?: DownloadOptions): Promise<OperationResult<Buffer | string>>;
+    moveItem(sourcePath: string, destinationPath: string, _options?: MoveOptions): Promise<OperationResult<FileSystemItem>>;
+    deleteFile(virtualPath: string): Promise<OperationResult>;
+    renameFile(virtualPath: string, newName: string, _options?: RenameOptions): Promise<OperationResult<FileItem>>;
+    renameFolder(virtualPath: string, newName: string, _options?: RenameOptions): Promise<OperationResult<FolderItem>>;
+    listDirectory(virtualPath: string, options?: ListOptions): Promise<OperationResult<FileSystemItem[]>>;
+    getItem(virtualPath: string): Promise<OperationResult<FileSystemItem>>;
+    exists(virtualPath: string): Promise<boolean>;
+    getFolderTree(path?: string, depth?: number): Promise<OperationResult<TreeNode[]>>;
+}
+/**
+ * Factory function to create a DropboxModule instance
+ */
+declare function createDropboxModule(): DropboxModule;
+
 /**
  * Module Registry
  * Central registry for all storage modules
@@ -2895,4 +3062,4 @@ 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, 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 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, 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 };
+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 };

package/dist/index.d.ts

@@ -514,7 +514,7 @@ interface UploadWithRefOptions {
  * Core types for the hazo_files package
  */
 /** Supported storage provider types */
-type StorageProvider = 'local' | 'google_drive';
+type StorageProvider = 'local' | 'google_drive' | 'dropbox';
 /** File item representing a file in storage */
 interface FileItem {
     id: string;
@@ -542,11 +542,21 @@ interface FolderItem {
 }
 /** Union type for file system items */
 type FileSystemItem = FileItem | FolderItem;
+/** Dropbox specific configuration */
+interface DropboxConfig {
+    clientId: string;
+    clientSecret: string;
+    redirectUri: string;
+    refreshToken?: string;
+    accessToken?: string;
+    rootPath?: string;
+}
 /** Configuration for the file manager */
 interface HazoFilesConfig {
     provider: StorageProvider;
     local?: LocalStorageConfig;
     google_drive?: GoogleDriveConfig;
+    dropbox?: DropboxConfig;
 }
 /** Local storage specific configuration */
 interface LocalStorageConfig {
@@ -1429,6 +1439,13 @@ interface HazoLLMInstance {
  * Factory function type for creating LLM instances
  */
 type LLMFactory = (provider: LLMProvider, options?: Record<string, unknown>) => HazoLLMInstance | Promise<HazoLLMInstance>;
+/**
+ * Extended LLM factory configuration with optional cache management
+ */
+interface LLMFactoryConfig {
+    create: LLMFactory;
+    invalidateCache?: (area?: string, key?: string) => void;
+}
 /**
  * LLM Extraction Service
  *
@@ -1470,7 +1487,13 @@ type LLMFactory = (provider: LLMProvider, options?: Record<string, unknown>) =>
 declare class LLMExtractionService {
     private llmFactory;
     private defaultProvider;
-    constructor(llmFactory: LLMFactory, defaultProvider?: LLMProvider);
+    private cacheInvalidator?;
+    constructor(factoryConfig: LLMFactoryConfig, defaultProvider?: LLMProvider);
+    /**
+     * Invalidate the LLM prompt cache
+     * Passthrough to hazo_llm_api's invalidate_prompt_cache when configured
+     */
+    invalidatePromptCache(area?: string, key?: string): void;
     /**
      * Extract data from a document
      *
@@ -1502,10 +1525,10 @@ declare class LLMExtractionService {
 /**
  * Create an LLMExtractionService instance
  *
- * @param llmFactory - Factory function for creating LLM instances
+ * @param factoryConfig - LLM factory configuration with create function and optional cache invalidation
  * @param defaultProvider - Default LLM provider (default: 'gemini')
  */
-declare function createLLMExtractionService(llmFactory: LLMFactory, defaultProvider?: LLMProvider): LLMExtractionService;
+declare function createLLMExtractionService(factoryConfig: LLMFactoryConfig, defaultProvider?: LLMProvider): LLMExtractionService;
 
 /**
  * Upload + Extract Service
@@ -2449,6 +2472,150 @@ declare class GoogleDriveModule extends BaseStorageModule {
  */
 declare function createGoogleDriveModule(): GoogleDriveModule;
 
+/**
+ * Dropbox OAuth Authentication Handler
+ * Manages OAuth flow, token storage, and token refresh
+ */
+interface DropboxAuthConfig {
+    clientId: string;
+    clientSecret: string;
+    redirectUri: string;
+}
+interface DropboxTokenData {
+    accessToken: string;
+    refreshToken: string;
+    expiryDate?: number;
+}
+interface DropboxAuthCallbacks {
+    onTokensUpdated?: (tokens: DropboxTokenData) => Promise<void>;
+    getStoredTokens?: () => Promise<DropboxTokenData | null>;
+}
+/**
+ * Dropbox Authentication Manager
+ */
+declare class DropboxAuth {
+    private config;
+    private callbacks;
+    private tokens;
+    constructor(config: DropboxAuthConfig, callbacks?: DropboxAuthCallbacks);
+    /**
+     * Generate the authorization URL for OAuth consent
+     */
+    getAuthUrl(state?: string): string;
+    /**
+     * Exchange authorization code for tokens
+     */
+    exchangeCodeForTokens(code: string): Promise<DropboxTokenData>;
+    /**
+     * Set tokens directly (e.g., from stored tokens)
+     */
+    setTokens(tokens: DropboxTokenData): Promise<void>;
+    /**
+     * Load tokens from storage using callback
+     */
+    loadStoredTokens(): Promise<boolean>;
+    /**
+     * Check if authenticated
+     */
+    isAuthenticated(): boolean;
+    /**
+     * Get current tokens
+     */
+    getTokens(): DropboxTokenData | null;
+    /**
+     * Get current access token
+     */
+    getAccessToken(): string | null;
+    /**
+     * Refresh the access token
+     */
+    refreshAccessToken(): Promise<DropboxTokenData>;
+    /**
+     * Revoke access (disconnect)
+     */
+    revokeAccess(): Promise<void>;
+    /**
+     * Check if token is expired or will expire soon
+     */
+    isTokenExpired(bufferSeconds?: number): boolean;
+    /**
+     * Ensure valid access token (refresh if needed)
+     */
+    ensureValidToken(): Promise<void>;
+}
+/**
+ * Create a new DropboxAuth instance
+ */
+declare function createDropboxAuth(config: DropboxAuthConfig, callbacks?: DropboxAuthCallbacks): DropboxAuth;
+
+/**
+ * Dropbox Storage Module
+ * Implements file operations using Dropbox API via the official SDK
+ */
+
+declare class DropboxModule extends BaseStorageModule {
+    readonly provider: StorageProvider;
+    private auth;
+    private dbx;
+    private rootPath;
+    private authCallbacks;
+    /**
+     * Set authentication callbacks for token persistence
+     */
+    setAuthCallbacks(callbacks: DropboxAuthCallbacks): void;
+    initialize(config: HazoFilesConfig): Promise<void>;
+    /**
+     * Create/recreate the Dropbox SDK client with the current access token
+     */
+    private createDropboxClient;
+    /**
+     * Get the auth instance for OAuth flow
+     */
+    getAuth(): DropboxAuth;
+    /**
+     * Check if user is authenticated
+     */
+    isAuthenticated(): boolean;
+    /**
+     * Authenticate with provided tokens
+     */
+    authenticate(tokens: DropboxTokenData): Promise<void>;
+    /**
+     * Ensure authenticated before operations
+     */
+    private ensureAuthenticated;
+    /**
+     * Convert virtual path to Dropbox path
+     * Virtual: /folder/file.txt -> Dropbox: /folder/file.txt (or /rootPath/folder/file.txt)
+     * Dropbox root is empty string "", not "/"
+     */
+    private toDropboxPath;
+    /**
+     * Convert Dropbox metadata to FileSystemItem
+     */
+    private metadataToItem;
+    /**
+     * Convert a Dropbox path_display to virtual path
+     */
+    private toVirtualPath;
+    createDirectory(virtualPath: string): Promise<OperationResult<FolderItem>>;
+    removeDirectory(virtualPath: string, recursive?: boolean): Promise<OperationResult>;
+    uploadFile(source: string | Buffer | ReadableStream, remotePath: string, options?: UploadOptions): Promise<OperationResult<FileItem>>;
+    downloadFile(remotePath: string, localPath?: string, options?: DownloadOptions): Promise<OperationResult<Buffer | string>>;
+    moveItem(sourcePath: string, destinationPath: string, _options?: MoveOptions): Promise<OperationResult<FileSystemItem>>;
+    deleteFile(virtualPath: string): Promise<OperationResult>;
+    renameFile(virtualPath: string, newName: string, _options?: RenameOptions): Promise<OperationResult<FileItem>>;
+    renameFolder(virtualPath: string, newName: string, _options?: RenameOptions): Promise<OperationResult<FolderItem>>;
+    listDirectory(virtualPath: string, options?: ListOptions): Promise<OperationResult<FileSystemItem[]>>;
+    getItem(virtualPath: string): Promise<OperationResult<FileSystemItem>>;
+    exists(virtualPath: string): Promise<boolean>;
+    getFolderTree(path?: string, depth?: number): Promise<OperationResult<TreeNode[]>>;
+}
+/**
+ * Factory function to create a DropboxModule instance
+ */
+declare function createDropboxModule(): DropboxModule;
+
 /**
  * Module Registry
  * Central registry for all storage modules
@@ -2895,4 +3062,4 @@ 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, 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 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, 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 };
+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 };