hazo_files 1.5.1 → 1.6.0

package/CHANGE_LOG.md

@@ -5,6 +5,27 @@ 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).
 
+## 1.6.0 (2026-05-21)
+
+### Added
+- **R2 Quota tracking**: Per-scope opt-in quota with threshold callbacks (`setQuotaLimit`, `getQuota`, `recomputeQuota`, `onQuotaThreshold`)
+- **R4 URL import**: `importFromUrl(url, path, opts)` with SSRF protection via `hazo_secure`, 50MB default cap, `source_url` column
+- **R6 Purge**: `createPurgeJobHandlers(fm)` factory + `HAZO_FILES_JOB_TYPES` constants for `hazo_jobs` integration
+- **Actor tracking**: Optional `actor_id` on all `TrackedFileManager` mutations → `changed_by`/`uploaded_by` columns
+- **Migrations 004-006**: `changed_by`, `source_url` columns, and `hazo_file_quotas` table
+- `HAZO_FILES_MIGRATION_V4` export for programmatic V4 migration
+- `HAZO_FILE_QUOTAS_TABLE_SCHEMA` export for quota table DDL
+- `QuotaService`, `QuotaExceededError`, `SSRFError`, `ImportSizeCapError` exported from `hazo_files/server`
+- test-app: Quota, URL Import, and Lifecycle pages with interactive scenarios
+
+### Not breaking
+All additions are opt-in or additive. Existing 1.5.x callers work without changes.
+
+## [1.5.2] - 2026-05-18
+
+### Fixed
+- `useFileUpload` no longer emits the React dev warning *"The result of getServerSnapshot should be cached to avoid an infinite loop"*. The third argument to `useSyncExternalStore` now points at a module-level frozen `EMPTY_ACTIVE_JOBS` constant instead of allocating a fresh `[]` per call, so React's reference identity check holds across renders.
+
 ## 1.5.0
 
 - **NEW**: `background_upload` module — UploadManager, Job, PipelineExecutor for pipelines that survive React component unmount.

package/README.md

@@ -21,6 +21,10 @@ 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
 - **Background Upload Pipelines**: Framework-agnostic `UploadManager` + React `HazoFileUploadProvider` for multi-step upload pipelines that survive component unmount, with optional sonner toast bridge
+- **Quota Tracking**: Per-scope opt-in quota with threshold callbacks and fail-open semantics
+- **URL Import**: `importFromUrl` with SSRF protection, streaming size cap, and `source_url` provenance tracking
+- **Actor Tracking**: Optional `actor_id` on all mutations, written to `uploaded_by` and `changed_by` columns
+- **Purge Scheduler**: `createPurgeJobHandlers` factory for integrating with hazo_jobs cron workers
 - **TypeScript**: Full type safety and IntelliSense support
 - **OAuth Integration**: Built-in Google Drive and Dropbox OAuth authentication
 - **Prompt Cache Invalidation**: Passthrough for hazo_llm_api prompt cache management via server instance
@@ -1981,6 +1985,187 @@ Contributions are welcome! Please:
 4. Add tests for new functionality
 5. Submit a pull request
 
+## Quota Tracking (v1.6.0)
+
+Per-scope opt-in quota tracking. A scope with no quota row has no limit — uploads succeed regardless (fail-open).
+
+### Setup
+
+Run migration 006 to create the `hazo_file_quotas` table (or use the `HAZO_FILE_QUOTAS_TABLE_SCHEMA` DDL export):
+
+```bash
+psql $DATABASE_URL < node_modules/hazo_files/migrations/006_quota_tracking.sql
+```
+
+Create a CRUD service and pass it to the factory:
+
+```typescript
+import { createHazoFilesServer, HAZO_FILE_QUOTAS_TABLE_SCHEMA } from 'hazo_files/server';
+
+const quotaCrud = createCrudService(adapter, HAZO_FILE_QUOTAS_TABLE_SCHEMA.tableName, {
+  primaryKeys: ['scope_id'],
+  autoId: { enabled: false },
+});
+
+const { fileManager } = await createHazoFilesServer({
+  crudService: fileCrud,
+  quotaCrudService: quotaCrud,
+  onQuotaThreshold: (event) => {
+    console.log(`Quota ${(event.percent * 100).toFixed(0)}% for scope ${event.scopeId}`);
+  },
+  quotaBands: [0.80, 0.95], // default
+  config: { provider: 'local', local: { basePath: './files' } },
+});
+```
+
+### Setting Quota Limits
+
+```typescript
+// Set a 10 GB limit for a scope
+const status = await fileManager.setQuotaLimit('scope-uuid', 10 * 1024 * 1024 * 1024);
+// { scopeId, byteLimit, byteUsed, percentUsed }
+
+// Check quota without uploading
+const quota = await fileManager.getQuota('scope-uuid');
+if (!quota) {
+  console.log('No quota set — unlimited');
+}
+```
+
+### Uploading with Quota Check
+
+When `scope_id` is passed to `uploadFile`, the quota is checked before the upload:
+
+```typescript
+// Throws QuotaExceededError if byteUsed + fileSize > byteLimit
+await fileManager.uploadFile(buffer, '/docs/report.pdf', { scope_id: 'scope-uuid' });
+```
+
+### Threshold Callbacks
+
+The `onQuotaThreshold` callback fires for each band crossed in a single operation. Both 80% and 95% can fire from one upload:
+
+```typescript
+onQuotaThreshold: (event) => {
+  if (event.percent === 0.80) notifyUser('Storage 80% full');
+  if (event.percent === 0.95) blockUploads('Storage 95% full');
+}
+```
+
+---
+
+## URL Import (v1.6.0)
+
+Import a file directly from a URL into virtual storage. Requires the optional peer dependency `hazo_secure`.
+
+### Installation
+
+```bash
+npm install hazo_secure   # optional peer dep
+```
+
+### Usage
+
+```typescript
+const result = await fileManager.importFromUrl(
+  'https://cdn.example.com/documents/report.pdf',
+  '/imports/report.pdf',
+  {
+    maxBytes: 50 * 1024 * 1024, // 50MB cap (default)
+    referrer: 'https://myapp.example.com/dashboard',
+    actor_id: 'user-uuid',      // written to uploaded_by + changed_by
+  }
+);
+// result.data: { virtualPath, size, sourceUrl }
+```
+
+The imported file's `source_url` column is set to the fetch URL for provenance tracking.
+
+### SSRF Protection
+
+Configure an allowlist in the server factory to restrict importable domains:
+
+```typescript
+const { fileManager } = await createHazoFilesServer({
+  ssrf: {
+    allowlist: ['cdn.example.com', 'assets.myapp.com'],
+  },
+  // ...
+});
+```
+
+Without an allowlist, private IPs (RFC-1918) are always blocked. Blocked requests throw `SSRFError`.
+
+### Size Cap
+
+If the response body exceeds `maxBytes`, the fetch is aborted and `ImportSizeCapError` is thrown. No partial file is left in storage.
+
+---
+
+## Actor Tracking (v1.6.0)
+
+All `TrackedFileManager` mutation methods accept an optional `actor_id` parameter:
+
+```typescript
+await fileManager.uploadFile(buffer, '/path/file.pdf', { actor_id: 'user-uuid' });
+await fileManager.moveItem('/old', '/new', { actor_id: 'user-uuid' });
+await fileManager.renameFile('/old.pdf', 'new.pdf', { actor_id: 'user-uuid' });
+await fileManager.renameFolder('/old-dir', 'new-dir', { actor_id: 'user-uuid' });
+await fileManager.deleteFile('/path/file.pdf', { actor_id: 'user-uuid' });
+await fileManager.softDeleteFile(fileId, { actor_id: 'user-uuid' });
+```
+
+When `actor_id` is provided:
+- `uploaded_by` is set on creation (uploadFile only)
+- `changed_by` is written on every mutation
+
+Run migrations 004 and 005 to add these columns to existing databases:
+
+```bash
+psql $DATABASE_URL < node_modules/hazo_files/migrations/004_changed_by.sql
+psql $DATABASE_URL < node_modules/hazo_files/migrations/005_source_url.sql
+```
+
+---
+
+## Purge via hazo_jobs (v1.6.0)
+
+`createPurgeJobHandlers` creates handlers compatible with hazo_jobs workers for scheduled hard-deletion of soft-deleted files.
+
+```typescript
+import { createPurgeJobHandlers, HAZO_FILES_JOB_TYPES } from 'hazo_files/server';
+
+const handlers = createPurgeJobHandlers(fm, {
+  submitJob: (type, payload) => jobs.submit({ type, payload }),
+});
+
+// Register with your hazo_jobs worker:
+worker.register(HAZO_FILES_JOB_TYPES.PURGE_PLAN, handlers[HAZO_FILES_JOB_TYPES.PURGE_PLAN]);
+worker.register(HAZO_FILES_JOB_TYPES.PURGE_ONE,  handlers[HAZO_FILES_JOB_TYPES.PURGE_ONE]);
+
+// Create schedule via hazo_jobs REST or admin UI:
+await jobs.schedules.create({
+  name: 'hazo_files_purge',
+  cron: '30 3 * * *',
+  type: HAZO_FILES_JOB_TYPES.PURGE_PLAN,
+  payload: { retentionDays: 30 },
+});
+```
+
+**purge_plan**: Finds all `soft_deleted` records older than `retentionDays` and submits individual `purge_one` jobs. Supports `dryRun: true` to return `wouldPurge` list without deleting.
+
+**purge_one**: Hard-deletes a single file's physical storage and DB record. Idempotent — no-op if record not found.
+
+**Note**: Quota is decremented at soft-delete time, not at purge time.
+
+---
+
+## Image Processing
+
+Image resizing, thumbnail generation, and EXIF extraction are provided by the companion package `hazo_images`, which depends on `hazo_files` for storage.
+
+---
+
 ## Support
 
 - GitHub Issues: [https://github.com/pub12/hazo_files/issues](https://github.com/pub12/hazo_files/issues)

package/SETUP_CHECKLIST.md

@@ -1297,6 +1297,102 @@ Run through this final checklist to ensure everything is working:
 - Verify hazo_files/ui is imported correctly
 - Check browser console for errors
 
+## Part 9: V4 Setup (1.6.0 Features)
+
+### 9.1 Run Migrations 004-006
+
+- [ ] Add actor tracking columns:
+  ```bash
+  psql $DATABASE_URL < node_modules/hazo_files/migrations/004_changed_by.sql
+  psql $DATABASE_URL < node_modules/hazo_files/migrations/005_source_url.sql
+  ```
+  *(For SQLite: run the commented-out `ALTER TABLE` statements manually)*
+
+- [ ] Create quota tracking table:
+  ```bash
+  psql $DATABASE_URL < node_modules/hazo_files/migrations/006_quota_tracking.sql
+  ```
+
+### 9.2 Quota Tracking (optional)
+
+- [ ] Create CRUD service for `hazo_file_quotas`:
+  ```typescript
+  import { HAZO_FILE_QUOTAS_TABLE_SCHEMA } from 'hazo_files/server';
+
+  const quotaCrud = createCrudService(adapter, HAZO_FILE_QUOTAS_TABLE_SCHEMA.tableName, {
+    primaryKeys: ['scope_id'],
+    autoId: { enabled: false },
+  });
+  ```
+
+- [ ] Pass to server factory:
+  ```typescript
+  const { fileManager } = await createHazoFilesServer({
+    quotaCrudService: quotaCrud,
+    onQuotaThreshold: (event) => {
+      console.log(`Scope ${event.scopeId} at ${(event.percent * 100).toFixed(0)}%`);
+    },
+    // ... other options
+  });
+  ```
+
+- [ ] Set quota limits for scopes:
+  ```typescript
+  await fileManager.setQuotaLimit(scopeId, 10 * 1024 * 1024 * 1024); // 10 GB
+  ```
+
+### 9.3 URL Import / SSRF Guard (optional)
+
+- [ ] Install optional peer dependency:
+  ```bash
+  npm install hazo_secure
+  ```
+
+- [ ] Configure SSRF allowlist in factory:
+  ```typescript
+  const { fileManager } = await createHazoFilesServer({
+    ssrf: { allowlist: ['cdn.example.com', 'assets.myapp.com'] },
+    // ...
+  });
+  ```
+
+- [ ] Use `importFromUrl` in your API route:
+  ```typescript
+  const result = await fileManager.importFromUrl(url, '/imports/file.pdf', {
+    actor_id: userId,
+    maxBytes: 50 * 1024 * 1024,
+  });
+  ```
+
+### 9.4 Purge Scheduler via hazo_jobs (optional)
+
+- [ ] Install hazo_jobs (separate package):
+  ```bash
+  npm install hazo_jobs
+  ```
+
+- [ ] Register purge handlers with your worker:
+  ```typescript
+  import { createPurgeJobHandlers, HAZO_FILES_JOB_TYPES } from 'hazo_files/server';
+
+  const handlers = createPurgeJobHandlers(fm, {
+    submitJob: (type, payload) => jobs.submit({ type, payload }),
+  });
+
+  worker.register(HAZO_FILES_JOB_TYPES.PURGE_PLAN, handlers[HAZO_FILES_JOB_TYPES.PURGE_PLAN]);
+  worker.register(HAZO_FILES_JOB_TYPES.PURGE_ONE,  handlers[HAZO_FILES_JOB_TYPES.PURGE_ONE]);
+  ```
+
+- [ ] Create recurring schedule:
+  ```typescript
+  await jobs.schedules.create({
+    name: 'hazo_files_purge',
+    cron: '30 3 * * *',   // 3:30 AM daily
+    type: HAZO_FILES_JOB_TYPES.PURGE_PLAN,
+    payload: { retentionDays: 30 },
+  });
+  ```
+
 ## Next Steps
 
 - [ ] Review [README.md](README.md) for advanced usage examples

package/dist/background-upload/react/index.js

@@ -391,6 +391,7 @@ function HazoFileUploadProvider({
 
 // src/background_upload/react/use-file-upload.ts
 var import_react4 = require("react");
+var EMPTY_ACTIVE_JOBS = Object.freeze([]);
 function useFileUpload() {
   const manager = (0, import_react4.useContext)(FileUploadContext);
   if (!manager) {
@@ -417,7 +418,7 @@ function useFileUpload() {
       snapshot_ref.current = next;
       return next;
     },
-    () => []
+    () => EMPTY_ACTIVE_JOBS
   );
   const submit_batch = (0, import_react4.useCallback)(
     (options) => manager.submit_batch(options),

package/dist/background-upload/react/index.mjs

@@ -351,6 +351,7 @@ function HazoFileUploadProvider({
 
 // src/background_upload/react/use-file-upload.ts
 import { useContext, useCallback, useRef as useRef2, useSyncExternalStore } from "react";
+var EMPTY_ACTIVE_JOBS = Object.freeze([]);
 function useFileUpload() {
   const manager = useContext(FileUploadContext);
   if (!manager) {
@@ -377,7 +378,7 @@ function useFileUpload() {
       snapshot_ref.current = next;
       return next;
     },
-    () => []
+    () => EMPTY_ACTIVE_JOBS
   );
   const submit_batch = useCallback(
     (options) => manager.submit_batch(options),