hazo_files 2.0.0 → 2.0.1

package/CHANGE_LOG.md

@@ -5,6 +5,30 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## 2.0.1 (2026-05-23)
+
+### Added
+
+- **`FileStorageProvider` interface** (`hazo_files/server`) — lightweight storage abstraction with `put`, `get`, `delete`, `exists`, `getSignedUrl`, and `probe` methods. Complements the existing `StorageModule`/`FileManager` stack for simpler use cases that don't need folder trees or metadata tracking.
+- **`AppFileServerProvider`** (`hazo_files/server`) — local-filesystem provider with HMAC-SHA256-signed download URLs. Constructor options: `root` (filesystem root), `hmac_secret`, and `default_ttl_seconds` (default 300s). Includes `verifySignedUrl(token, path)` for use in the `/api/files/serve` API route. Path traversal is blocked at the `resolve()` layer.
+- **`InMemoryProvider`** (`hazo_files/testing`) — in-memory `FileStorageProvider` backed by a `Map<string, Buffer>`. Intended for unit tests. `getSignedUrl` returns a `data:` URL so tests never need a real HTTP server. Includes `snapshot()` escape hatch for assertions.
+- **`GoogleDriveProvider`** (`hazo_files/server`) — service-account Google Drive provider for Shared Drives. Accepts `service_account_json`, `shared_drive_id`, and a `DrivePathCache` for lazy folder-ID resolution. Unlike `GoogleDriveModule` (which uses OAuth), this provider is designed for server-side use with a GCP service account.
+- **`hazo_files/testing` subpath export** — re-exports `InMemoryProvider` for use in test suites without pulling in server-only modules.
+- **Error classes**: `StorageCollisionExhausted`, `StorageNotConfigured`, `StorageUnavailable` — exported from `hazo_files/server`.
+- **Types**: `PutOpts`, `PutResult`, `SignedUrlOpts`, `ProbeResult`, `DrivePathCache` — exported from `hazo_files/server`.
+
+### Breaking changes from 1.x
+None. All additions are new exports; existing `FileManager`/`TrackedFileManager` API is unchanged.
+
+## 2.0.0 (2026-05-22)
+
+### Changed
+
+- **`googleapis` and `mime-types` promoted to direct `dependencies`** (previously optional peer deps) — the package now bundles them so consumers no longer need to install them separately for Google Drive or MIME detection. This is a major bump because it changes the transitive dependency surface for all consumers.
+
+### Not breaking
+The public API is identical to 1.6.0. No migration required.
+
 ## 1.6.0 (2026-05-21)
 
 ### Added

package/README.md

@@ -7,6 +7,10 @@ A powerful, modular file management package for Node.js and React applications w
 
 ## Features
 
+- **`FileStorageProvider` Interface**: Lightweight `put/get/delete/exists/getSignedUrl/probe` abstraction for simpler use cases
+- **`AppFileServerProvider`**: Local filesystem + HMAC-signed download URLs — no cloud account required
+- **`GoogleDriveProvider`**: Service-account Google Drive for Shared Drives with lazy path-cache
+- **`InMemoryProvider`**: Zero-dependency in-memory store for unit tests (via `hazo_files/testing`)
 - **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
@@ -72,6 +76,17 @@ For the background-upload sonner toast bridge (optional):
 npm install sonner            # Toast notifications for background upload pipelines
 ```
 
+### Subpath exports
+
+| Import | Contents |
+|--------|---------|
+| `hazo_files` | Core types, utilities, naming helpers |
+| `hazo_files/ui` | React components (FileBrowser, NamingRuleConfigurator, etc.) |
+| `hazo_files/server` | Server-only: FileManager, TrackedFileManager, FileStorageProvider providers, schema exports |
+| `hazo_files/background-upload` | Framework-agnostic UploadManager pipeline engine |
+| `hazo_files/background-upload/react` | React bindings for background uploads |
+| `hazo_files/testing` | `InMemoryProvider` — import in test suites, safe to use without `server-only` |
+
 ### Tailwind CSS v4 Setup (Required for UI Components)
 
 If you're using Tailwind CSS v4 with the UI components, you must add a `@source` directive to your CSS file to ensure Tailwind scans the package's files for utility classes.
@@ -1866,6 +1881,152 @@ try {
 }
 ```
 
+## FileStorageProvider (v2 Provider API)
+
+v2 introduces a slimmer storage abstraction — `FileStorageProvider` — that sits alongside (not replacing) the existing `FileManager`/`StorageModule` stack. Use it when you don't need folder trees, metadata tracking, or naming conventions, and just want put/get/signed-URL semantics.
+
+### Interface
+
+```typescript
+import type { FileStorageProvider } from 'hazo_files/server';
+
+interface FileStorageProvider {
+  put(path: string, body: Buffer | Readable, opts?: PutOpts): Promise<PutResult>;
+  get(path: string): Promise<Buffer | Readable>;
+  delete(path: string): Promise<void>;
+  exists(path: string): Promise<boolean>;
+  getSignedUrl(path: string, opts?: SignedUrlOpts): Promise<string>;
+  probe(): Promise<ProbeResult>;
+}
+```
+
+### AppFileServerProvider
+
+Local filesystem with HMAC-signed download URLs. Ideal for self-hosted apps where files are served through an API route.
+
+```typescript
+import { AppFileServerProvider } from 'hazo_files/server';
+
+const provider = new AppFileServerProvider({
+  root: './storage',          // filesystem root
+  hmac_secret: process.env.FILE_HMAC_SECRET!,
+  default_ttl_seconds: 300,   // default 5 min
+});
+
+// Store a file
+const result = await provider.put('uploads/report.pdf', buffer, {
+  contentType: 'application/pdf',
+});
+// { provider: 'app_file_server', native_id: 'uploads/report.pdf', size: 12345 }
+
+// Generate a signed URL (expires in 5 min)
+const url = await provider.getSignedUrl('uploads/report.pdf');
+// '/api/files/serve/1748080800.ABC123.../uploads/report.pdf'
+```
+
+#### Serving signed URLs (Next.js API route)
+
+```typescript
+// app/api/files/serve/[...token]/route.ts
+import { NextRequest, NextResponse } from 'next/server';
+import { AppFileServerProvider } from 'hazo_files/server';
+
+const provider = new AppFileServerProvider({
+  root: './storage',
+  hmac_secret: process.env.FILE_HMAC_SECRET!,
+});
+
+export async function GET(
+  _req: NextRequest,
+  { params }: { params: { token: string[] } }
+) {
+  // token = ['<exp>.<sig>', 'uploads', 'report.pdf']
+  const [token, ...pathParts] = params.token;
+  const filePath = pathParts.join('/');
+
+  if (!provider.verifySignedUrl(token, filePath)) {
+    return new NextResponse('Forbidden', { status: 403 });
+  }
+
+  const buf = await provider.get(filePath) as Buffer;
+  return new NextResponse(buf, {
+    headers: { 'Content-Type': 'application/octet-stream' },
+  });
+}
+```
+
+### GoogleDriveProvider
+
+Service-account Google Drive for Shared Drives. No OAuth flow — configure a GCP service account with Shared Drive access.
+
+```typescript
+import { GoogleDriveProvider } from 'hazo_files/server';
+import type { DrivePathCache } from 'hazo_files/server';
+
+// Implement the path cache (e.g., backed by your hazo_connect adapter)
+const pathCache: DrivePathCache = {
+  lookup: async (key) => redis.get(`gdrive:${key}`),
+  write:  async (key, id) => redis.set(`gdrive:${key}`, id),
+  invalidate: async (key) => redis.del(`gdrive:${key}`),
+};
+
+const provider = new GoogleDriveProvider({
+  service_account_json: process.env.GOOGLE_SERVICE_ACCOUNT_JSON!,
+  shared_drive_id: 'your-shared-drive-id',
+  path_cache: pathCache,
+});
+
+// Upload a file (folders are created lazily)
+const result = await provider.put('2026/ACME/invoice.pdf', buffer, {
+  contentType: 'application/pdf',
+});
+// { provider: 'gdrive', native_id: '<drive-file-id>', size: 12345 }
+
+// Check connectivity
+const health = await provider.probe();
+// { ok: true } or { ok: false, error: 'drive_not_shared', message: '...' }
+```
+
+**Note**: `getSignedUrl` for Google Drive returns a native `drive.google.com/uc?id=...` link, which requires the viewer to have Drive access. For public unauthenticated downloads, use `AppFileServerProvider` instead or implement your own proxy.
+
+### InMemoryProvider (testing)
+
+Import from the dedicated `hazo_files/testing` subpath — keeps server-only modules out of your test bundle.
+
+```typescript
+import { InMemoryProvider } from 'hazo_files/testing';
+
+const store = new InMemoryProvider();
+
+await store.put('docs/readme.txt', Buffer.from('hello'));
+const buf = await store.get('docs/readme.txt');
+console.log(buf.toString()); // 'hello'
+
+// Test helper: inspect internal state
+const snap = store.snapshot();
+console.log([...snap.keys()]); // ['docs/readme.txt']
+
+// getSignedUrl returns a data: URL — no HTTP server needed
+const url = await store.getSignedUrl('docs/readme.txt');
+// 'data:application/octet-stream;base64,aGVsbG8='
+```
+
+### Provider Errors
+
+```typescript
+import {
+  StorageCollisionExhausted,
+  StorageNotConfigured,
+  StorageUnavailable,
+} from 'hazo_files/server';
+
+// StorageCollisionExhausted — thrown when put with ifNotExists keeps colliding
+// StorageNotConfigured     — thrown when provider config is absent
+// StorageUnavailable       — wraps a ProbeResult error for runtime checks
+```
+
+---
+
 ## Extending with Custom Storage Providers
 
 See [docs/ADDING_MODULES.md](docs/ADDING_MODULES.md) for a complete guide on creating custom storage modules.

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

package/dist/server/index.js

@@ -47,6 +47,7 @@ __export(index_exports, {
   FileTooLargeError: () => FileTooLargeError,
   GoogleDriveAuth: () => GoogleDriveAuth,
   GoogleDriveModule: () => GoogleDriveModule,
+  GoogleDriveProvider: () => GoogleDriveProvider,
   HAZO_FILES_DEFAULT_TABLE_NAME: () => HAZO_FILES_DEFAULT_TABLE_NAME,
   HAZO_FILES_JOB_TYPES: () => HAZO_FILES_JOB_TYPES,
   HAZO_FILES_MIGRATION_V2: () => HAZO_FILES_MIGRATION_V2,
@@ -59,6 +60,7 @@ __export(index_exports, {
   HAZO_FILE_QUOTAS_TABLE_SCHEMA: () => HAZO_FILE_QUOTAS_TABLE_SCHEMA,
   HazoFilesError: () => HazoFilesError,
   ImportSizeCapError: () => ImportSizeCapError,
+  InMemoryProvider: () => InMemoryProvider,
   InvalidExtensionError: () => InvalidExtensionError,
   InvalidPathError: () => InvalidPathError,
   LLMExtractionService: () => LLMExtractionService,
@@ -6554,6 +6556,194 @@ async function streamToBuffer(s) {
   return Buffer.concat(chunks);
 }
 
+// src/providers/in-memory.ts
+var InMemoryProvider = class {
+  constructor() {
+    this.provider_tag = "in_memory";
+    this.store = /* @__PURE__ */ new Map();
+  }
+  async put(path4, body, opts) {
+    if (opts?.ifNotExists && this.store.has(path4)) throw new Error(`File exists: ${path4}`);
+    const buf = Buffer.isBuffer(body) ? body : await streamToBuffer2(body);
+    this.store.set(path4, buf);
+    return { provider: this.provider_tag, native_id: path4, size: buf.length };
+  }
+  async get(path4) {
+    const buf = this.store.get(path4);
+    if (!buf) throw new Error(`Not found: ${path4}`);
+    return buf;
+  }
+  async delete(path4) {
+    this.store.delete(path4);
+  }
+  async exists(path4) {
+    return this.store.has(path4);
+  }
+  async getSignedUrl(path4, _opts) {
+    const buf = this.store.get(path4);
+    if (!buf) throw new Error(`Not found: ${path4}`);
+    return `data:application/octet-stream;base64,${buf.toString("base64")}`;
+  }
+  async probe() {
+    return { ok: true };
+  }
+  /** Test-only escape hatch — exposes the internal store for assertions. */
+  snapshot() {
+    return new Map(this.store);
+  }
+};
+async function streamToBuffer2(s) {
+  const chunks = [];
+  for await (const c of s) chunks.push(Buffer.isBuffer(c) ? c : Buffer.from(c));
+  return Buffer.concat(chunks);
+}
+
+// src/providers/google-drive.ts
+var import_googleapis3 = require("googleapis");
+var GoogleDriveProvider = class {
+  constructor(opts) {
+    this.provider_tag = "gdrive";
+    let credentials = {};
+    try {
+      credentials = JSON.parse(opts.service_account_json);
+    } catch {
+    }
+    const auth = new import_googleapis3.google.auth.GoogleAuth({
+      credentials,
+      scopes: ["https://www.googleapis.com/auth/drive"]
+    });
+    this.drive = import_googleapis3.google.drive({ version: "v3", auth });
+    this.driveId = opts.shared_drive_id;
+    this.cache = opts.path_cache;
+  }
+  async probe() {
+    try {
+      await this.drive.drives.get({
+        driveId: this.driveId,
+        supportsAllDrives: true
+      });
+      return { ok: true };
+    } catch (err) {
+      const e = err;
+      if (e?.code === 404) return { ok: false, error: "drive_not_shared", message: "SA cannot see Shared Drive" };
+      if (e?.code === 403) return { ok: false, error: "write_denied", message: "SA lacks permission" };
+      return { ok: false, error: "transient", message: String(err) };
+    }
+  }
+  async put(path4, body, opts) {
+    const segments = path4.split("/").filter(Boolean);
+    const filename = segments.pop();
+    const parentId = await this.resolvePath(segments, { create: true });
+    if (opts?.ifNotExists) {
+      const existing = await this.findChild(filename, parentId);
+      if (existing) throw new Error(`File exists: ${path4}`);
+    }
+    const buf = Buffer.isBuffer(body) ? body : await streamToBuffer3(body);
+    const res = await this.drive.files.create({
+      requestBody: {
+        name: filename,
+        parents: [parentId],
+        mimeType: opts?.contentType ?? "application/octet-stream"
+      },
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      media: { body: buf },
+      fields: "id, name"
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    });
+    return { provider: this.provider_tag, native_id: res.data.id, size: buf.length };
+  }
+  async get(path4) {
+    const id = await this.lookupFileId(path4);
+    const res = await this.drive.files.get(
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      { fileId: id, alt: "media", supportsAllDrives: true },
+      { responseType: "arraybuffer" }
+    );
+    return Buffer.from(res.data);
+  }
+  async delete(path4) {
+    try {
+      const id = await this.lookupFileId(path4);
+      await this.drive.files.delete({ fileId: id, supportsAllDrives: true });
+    } catch (err) {
+      const e = err;
+      if (e?.code !== 404) throw err;
+    }
+  }
+  async exists(path4) {
+    try {
+      await this.lookupFileId(path4);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  async getSignedUrl(path4, _opts) {
+    const id = await this.lookupFileId(path4);
+    return `https://drive.google.com/uc?id=${id}&export=download`;
+  }
+  async resolvePath(segments, opts) {
+    let parentId = this.driveId;
+    const accumulated = [];
+    for (const segment of segments) {
+      accumulated.push(segment);
+      const cacheKey = accumulated.join("/");
+      const cached = await this.cache.lookup(cacheKey);
+      if (cached) {
+        parentId = cached;
+        continue;
+      }
+      let found = await this.findChild(segment, parentId, "application/vnd.google-apps.folder");
+      if (!found && opts.create) {
+        const created = await this.drive.files.create({
+          requestBody: {
+            name: segment,
+            parents: [parentId],
+            mimeType: "application/vnd.google-apps.folder"
+          },
+          fields: "id"
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        });
+        found = created.data.id;
+      }
+      if (!found) throw new Error(`Folder not found and create=false: ${cacheKey}`);
+      await this.cache.write(cacheKey, found);
+      parentId = found;
+    }
+    return parentId;
+  }
+  async findChild(name, parentId, mimeType) {
+    const q = [
+      `name='${name.replace(/'/g, "\\'")}'`,
+      `'${parentId}' in parents`,
+      `trashed=false`
+    ];
+    if (mimeType) q.push(`mimeType='${mimeType}'`);
+    const res = await this.drive.files.list({
+      q: q.join(" and "),
+      driveId: this.driveId,
+      corpora: "drive",
+      includeItemsFromAllDrives: true,
+      fields: "files(id, name)"
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    });
+    return res.data.files?.[0]?.id ?? null;
+  }
+  async lookupFileId(path4) {
+    const segments = path4.split("/").filter(Boolean);
+    const filename = segments.pop();
+    const parentId = await this.resolvePath(segments, { create: false });
+    const id = await this.findChild(filename, parentId);
+    if (!id) throw Object.assign(new Error(`Not found: ${path4}`), { code: 404 });
+    return id;
+  }
+};
+async function streamToBuffer3(s) {
+  const chunks = [];
+  for await (const c of s) chunks.push(Buffer.isBuffer(c) ? c : Buffer.from(c));
+  return Buffer.concat(chunks);
+}
+
 // src/providers/types.ts
 var StorageCollisionExhausted = class extends Error {
   constructor(attempts, lastPath) {
@@ -6636,6 +6826,7 @@ try {
   FileTooLargeError,
   GoogleDriveAuth,
   GoogleDriveModule,
+  GoogleDriveProvider,
   HAZO_FILES_DEFAULT_TABLE_NAME,
   HAZO_FILES_JOB_TYPES,
   HAZO_FILES_MIGRATION_V2,
@@ -6648,6 +6839,7 @@ try {
   HAZO_FILE_QUOTAS_TABLE_SCHEMA,
   HazoFilesError,
   ImportSizeCapError,
+  InMemoryProvider,
   InvalidExtensionError,
   InvalidPathError,
   LLMExtractionService,

package/dist/server/index.mjs

@@ -6368,6 +6368,194 @@ async function streamToBuffer(s) {
   return Buffer.concat(chunks);
 }
 
+// src/providers/in-memory.ts
+var InMemoryProvider = class {
+  constructor() {
+    this.provider_tag = "in_memory";
+    this.store = /* @__PURE__ */ new Map();
+  }
+  async put(path4, body, opts) {
+    if (opts?.ifNotExists && this.store.has(path4)) throw new Error(`File exists: ${path4}`);
+    const buf = Buffer.isBuffer(body) ? body : await streamToBuffer2(body);
+    this.store.set(path4, buf);
+    return { provider: this.provider_tag, native_id: path4, size: buf.length };
+  }
+  async get(path4) {
+    const buf = this.store.get(path4);
+    if (!buf) throw new Error(`Not found: ${path4}`);
+    return buf;
+  }
+  async delete(path4) {
+    this.store.delete(path4);
+  }
+  async exists(path4) {
+    return this.store.has(path4);
+  }
+  async getSignedUrl(path4, _opts) {
+    const buf = this.store.get(path4);
+    if (!buf) throw new Error(`Not found: ${path4}`);
+    return `data:application/octet-stream;base64,${buf.toString("base64")}`;
+  }
+  async probe() {
+    return { ok: true };
+  }
+  /** Test-only escape hatch — exposes the internal store for assertions. */
+  snapshot() {
+    return new Map(this.store);
+  }
+};
+async function streamToBuffer2(s) {
+  const chunks = [];
+  for await (const c of s) chunks.push(Buffer.isBuffer(c) ? c : Buffer.from(c));
+  return Buffer.concat(chunks);
+}
+
+// src/providers/google-drive.ts
+import { google as google3 } from "googleapis";
+var GoogleDriveProvider = class {
+  constructor(opts) {
+    this.provider_tag = "gdrive";
+    let credentials = {};
+    try {
+      credentials = JSON.parse(opts.service_account_json);
+    } catch {
+    }
+    const auth = new google3.auth.GoogleAuth({
+      credentials,
+      scopes: ["https://www.googleapis.com/auth/drive"]
+    });
+    this.drive = google3.drive({ version: "v3", auth });
+    this.driveId = opts.shared_drive_id;
+    this.cache = opts.path_cache;
+  }
+  async probe() {
+    try {
+      await this.drive.drives.get({
+        driveId: this.driveId,
+        supportsAllDrives: true
+      });
+      return { ok: true };
+    } catch (err) {
+      const e = err;
+      if (e?.code === 404) return { ok: false, error: "drive_not_shared", message: "SA cannot see Shared Drive" };
+      if (e?.code === 403) return { ok: false, error: "write_denied", message: "SA lacks permission" };
+      return { ok: false, error: "transient", message: String(err) };
+    }
+  }
+  async put(path4, body, opts) {
+    const segments = path4.split("/").filter(Boolean);
+    const filename = segments.pop();
+    const parentId = await this.resolvePath(segments, { create: true });
+    if (opts?.ifNotExists) {
+      const existing = await this.findChild(filename, parentId);
+      if (existing) throw new Error(`File exists: ${path4}`);
+    }
+    const buf = Buffer.isBuffer(body) ? body : await streamToBuffer3(body);
+    const res = await this.drive.files.create({
+      requestBody: {
+        name: filename,
+        parents: [parentId],
+        mimeType: opts?.contentType ?? "application/octet-stream"
+      },
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      media: { body: buf },
+      fields: "id, name"
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    });
+    return { provider: this.provider_tag, native_id: res.data.id, size: buf.length };
+  }
+  async get(path4) {
+    const id = await this.lookupFileId(path4);
+    const res = await this.drive.files.get(
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      { fileId: id, alt: "media", supportsAllDrives: true },
+      { responseType: "arraybuffer" }
+    );
+    return Buffer.from(res.data);
+  }
+  async delete(path4) {
+    try {
+      const id = await this.lookupFileId(path4);
+      await this.drive.files.delete({ fileId: id, supportsAllDrives: true });
+    } catch (err) {
+      const e = err;
+      if (e?.code !== 404) throw err;
+    }
+  }
+  async exists(path4) {
+    try {
+      await this.lookupFileId(path4);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  async getSignedUrl(path4, _opts) {
+    const id = await this.lookupFileId(path4);
+    return `https://drive.google.com/uc?id=${id}&export=download`;
+  }
+  async resolvePath(segments, opts) {
+    let parentId = this.driveId;
+    const accumulated = [];
+    for (const segment of segments) {
+      accumulated.push(segment);
+      const cacheKey = accumulated.join("/");
+      const cached = await this.cache.lookup(cacheKey);
+      if (cached) {
+        parentId = cached;
+        continue;
+      }
+      let found = await this.findChild(segment, parentId, "application/vnd.google-apps.folder");
+      if (!found && opts.create) {
+        const created = await this.drive.files.create({
+          requestBody: {
+            name: segment,
+            parents: [parentId],
+            mimeType: "application/vnd.google-apps.folder"
+          },
+          fields: "id"
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        });
+        found = created.data.id;
+      }
+      if (!found) throw new Error(`Folder not found and create=false: ${cacheKey}`);
+      await this.cache.write(cacheKey, found);
+      parentId = found;
+    }
+    return parentId;
+  }
+  async findChild(name, parentId, mimeType) {
+    const q = [
+      `name='${name.replace(/'/g, "\\'")}'`,
+      `'${parentId}' in parents`,
+      `trashed=false`
+    ];
+    if (mimeType) q.push(`mimeType='${mimeType}'`);
+    const res = await this.drive.files.list({
+      q: q.join(" and "),
+      driveId: this.driveId,
+      corpora: "drive",
+      includeItemsFromAllDrives: true,
+      fields: "files(id, name)"
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    });
+    return res.data.files?.[0]?.id ?? null;
+  }
+  async lookupFileId(path4) {
+    const segments = path4.split("/").filter(Boolean);
+    const filename = segments.pop();
+    const parentId = await this.resolvePath(segments, { create: false });
+    const id = await this.findChild(filename, parentId);
+    if (!id) throw Object.assign(new Error(`Not found: ${path4}`), { code: 404 });
+    return id;
+  }
+};
+async function streamToBuffer3(s) {
+  const chunks = [];
+  for await (const c of s) chunks.push(Buffer.isBuffer(c) ? c : Buffer.from(c));
+  return Buffer.concat(chunks);
+}
+
 // src/providers/types.ts
 var StorageCollisionExhausted = class extends Error {
   constructor(attempts, lastPath) {
@@ -6449,6 +6637,7 @@ export {
   FileTooLargeError,
   GoogleDriveAuth,
   GoogleDriveModule,
+  GoogleDriveProvider,
   HAZO_FILES_DEFAULT_TABLE_NAME,
   HAZO_FILES_JOB_TYPES,
   HAZO_FILES_MIGRATION_V2,
@@ -6461,6 +6650,7 @@ export {
   HAZO_FILE_QUOTAS_TABLE_SCHEMA,
   HazoFilesError,
   ImportSizeCapError,
+  InMemoryProvider,
   InvalidExtensionError,
   InvalidPathError,
   LLMExtractionService,

package/dist/testing/index.d.mts

@@ -0,0 +1,62 @@
+import { Readable } from 'node:stream';
+
+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>;
+}
+
+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>;
+}
+
+export { InMemoryProvider };

package/dist/testing/index.d.ts

@@ -0,0 +1,62 @@
+import { Readable } from 'node:stream';
+
+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>;
+}
+
+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>;
+}
+
+export { InMemoryProvider };

package/dist/testing/index.js

@@ -0,0 +1,71 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/testing/index.ts
+var index_exports = {};
+__export(index_exports, {
+  InMemoryProvider: () => InMemoryProvider
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/providers/in-memory.ts
+var InMemoryProvider = class {
+  constructor() {
+    this.provider_tag = "in_memory";
+    this.store = /* @__PURE__ */ new Map();
+  }
+  async put(path, body, opts) {
+    if (opts?.ifNotExists && this.store.has(path)) throw new Error(`File exists: ${path}`);
+    const buf = Buffer.isBuffer(body) ? body : await streamToBuffer(body);
+    this.store.set(path, buf);
+    return { provider: this.provider_tag, native_id: path, size: buf.length };
+  }
+  async get(path) {
+    const buf = this.store.get(path);
+    if (!buf) throw new Error(`Not found: ${path}`);
+    return buf;
+  }
+  async delete(path) {
+    this.store.delete(path);
+  }
+  async exists(path) {
+    return this.store.has(path);
+  }
+  async getSignedUrl(path, _opts) {
+    const buf = this.store.get(path);
+    if (!buf) throw new Error(`Not found: ${path}`);
+    return `data:application/octet-stream;base64,${buf.toString("base64")}`;
+  }
+  async probe() {
+    return { ok: true };
+  }
+  /** Test-only escape hatch — exposes the internal store for assertions. */
+  snapshot() {
+    return new Map(this.store);
+  }
+};
+async function streamToBuffer(s) {
+  const chunks = [];
+  for await (const c of s) chunks.push(Buffer.isBuffer(c) ? c : Buffer.from(c));
+  return Buffer.concat(chunks);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  InMemoryProvider
+});

package/dist/testing/index.mjs

@@ -0,0 +1,44 @@
+// src/providers/in-memory.ts
+var InMemoryProvider = class {
+  constructor() {
+    this.provider_tag = "in_memory";
+    this.store = /* @__PURE__ */ new Map();
+  }
+  async put(path, body, opts) {
+    if (opts?.ifNotExists && this.store.has(path)) throw new Error(`File exists: ${path}`);
+    const buf = Buffer.isBuffer(body) ? body : await streamToBuffer(body);
+    this.store.set(path, buf);
+    return { provider: this.provider_tag, native_id: path, size: buf.length };
+  }
+  async get(path) {
+    const buf = this.store.get(path);
+    if (!buf) throw new Error(`Not found: ${path}`);
+    return buf;
+  }
+  async delete(path) {
+    this.store.delete(path);
+  }
+  async exists(path) {
+    return this.store.has(path);
+  }
+  async getSignedUrl(path, _opts) {
+    const buf = this.store.get(path);
+    if (!buf) throw new Error(`Not found: ${path}`);
+    return `data:application/octet-stream;base64,${buf.toString("base64")}`;
+  }
+  async probe() {
+    return { ok: true };
+  }
+  /** Test-only escape hatch — exposes the internal store for assertions. */
+  snapshot() {
+    return new Map(this.store);
+  }
+};
+async function streamToBuffer(s) {
+  const chunks = [];
+  for await (const c of s) chunks.push(Buffer.isBuffer(c) ? c : Buffer.from(c));
+  return Buffer.concat(chunks);
+}
+export {
+  InMemoryProvider
+};

package/docs/superpowers/plans/2026-05-23-test-app-v2-providers.md

@@ -8,7 +8,7 @@
 - [x] Task 4: Signed-URL serve route — 0983dfa (2026-05-23)
 - [x] Task 5: AppFileServerProvider scenario page — fdff8ec (2026-05-23)
 - [x] Task 6: Stub pages (InMemory + GDrive) — d815df6 (2026-05-23)
-- [ ] Task 7: Smoke test — manual browser verification needed
+- [x] Task 7: Smoke test — passed, published to npm (2026-05-23)
 
 > **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hazo_files",
-  "version": "2.0.0",
+  "version": "2.0.1",
   "description": "File management including integration to cloud files",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -30,6 +30,11 @@
       "types": "./dist/background-upload/react/index.d.ts",
       "import": "./dist/background-upload/react/index.mjs",
       "require": "./dist/background-upload/react/index.js"
+    },
+    "./testing": {
+      "types": "./dist/testing/index.d.ts",
+      "import": "./dist/testing/index.mjs",
+      "require": "./dist/testing/index.js"
     }
   },
   "files": [
@@ -47,7 +52,8 @@
   },
   "sideEffects": false,
   "scripts": {
-    "build": "npm run build:main && npm run build:ui && npm run build:server && npm run build:bg-upload && npm run build:bg-upload-react",
+    "build": "npm run build:main && npm run build:ui && npm run build:server && npm run build:bg-upload && npm run build:bg-upload-react && npm run build:testing",
+    "build:testing": "tsup src/testing/index.ts --outDir dist/testing --dts --format cjs,esm --no-clean",
     "build:main": "tsup src/index.ts --dts --format cjs,esm --clean",
     "build:ui": "tsup src/ui/index.ts --outDir dist/ui --dts --format cjs,esm --no-clean --external react --external react-dom --external @dnd-kit/core --external @dnd-kit/sortable --external @dnd-kit/utilities",
     "build:server": "tsup src/server/index.ts --outDir dist/server --dts --format cjs,esm --no-clean",