hazo_files 1.4.6 → 1.4.7

package/README.md

@@ -510,6 +510,167 @@ const fileManager = await createInitializedFileManager({
 });
 ```
 
+## Database Schema
+
+Database tables are only required if you use `TrackedFileManager`, `FileMetadataService`, `NamingConventionService`, or `UploadExtractService`. Plain `FileManager` (filesystem only) needs no tables.
+
+There are two tables:
+
+- **`hazo_files`** — file metadata, hashes, references, content tags
+- **`hazo_files_naming`** — saved naming conventions
+
+The DDL below is also exposed programmatically via `HAZO_FILES_TABLE_SCHEMA` and `HAZO_FILES_NAMING_TABLE_SCHEMA` (see [Programmatic Setup](#programmatic-setup) below). Run the raw SQL if you prefer to manage migrations with your existing tooling (psql, sqlite3, Flyway, Knex, etc.).
+
+### `hazo_files` Table
+
+#### PostgreSQL
+
+```sql
+CREATE TABLE IF NOT EXISTS hazo_files (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  filename TEXT NOT NULL,
+  file_type TEXT NOT NULL,
+  file_data TEXT DEFAULT '{}',
+  created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
+  changed_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
+  file_path TEXT NOT NULL,
+  storage_type TEXT NOT NULL,
+  file_hash TEXT,
+  file_size BIGINT,
+  file_changed_at TIMESTAMP WITH TIME ZONE,
+  file_refs TEXT DEFAULT '[]',
+  ref_count INTEGER DEFAULT 0,
+  status TEXT DEFAULT 'active',
+  scope_id UUID,
+  uploaded_by UUID,
+  storage_verified_at TIMESTAMP WITH TIME ZONE,
+  deleted_at TIMESTAMP WITH TIME ZONE,
+  original_filename TEXT,
+  content_tag TEXT
+);
+
+CREATE INDEX IF NOT EXISTS idx_hazo_files_path ON hazo_files (file_path);
+CREATE INDEX IF NOT EXISTS idx_hazo_files_storage ON hazo_files (storage_type);
+CREATE UNIQUE INDEX IF NOT EXISTS idx_hazo_files_path_storage ON hazo_files (file_path, storage_type);
+CREATE INDEX IF NOT EXISTS idx_hazo_files_hash ON hazo_files (file_hash);
+CREATE INDEX IF NOT EXISTS idx_hazo_files_status ON hazo_files (status);
+CREATE INDEX IF NOT EXISTS idx_hazo_files_scope ON hazo_files (scope_id);
+CREATE INDEX IF NOT EXISTS idx_hazo_files_ref_count ON hazo_files (ref_count);
+CREATE INDEX IF NOT EXISTS idx_hazo_files_deleted ON hazo_files (deleted_at);
+CREATE INDEX IF NOT EXISTS idx_hazo_files_content_tag ON hazo_files (content_tag);
+```
+
+#### SQLite
+
+```sql
+CREATE TABLE IF NOT EXISTS hazo_files (
+  id TEXT PRIMARY KEY,
+  filename TEXT NOT NULL,
+  file_type TEXT NOT NULL,
+  file_data TEXT DEFAULT '{}',
+  created_at TEXT NOT NULL,
+  changed_at TEXT NOT NULL,
+  file_path TEXT NOT NULL,
+  storage_type TEXT NOT NULL,
+  file_hash TEXT,
+  file_size INTEGER,
+  file_changed_at TEXT,
+  file_refs TEXT DEFAULT '[]',
+  ref_count INTEGER DEFAULT 0,
+  status TEXT DEFAULT 'active',
+  scope_id TEXT,
+  uploaded_by TEXT,
+  storage_verified_at TEXT,
+  deleted_at TEXT,
+  original_filename TEXT,
+  content_tag TEXT
+);
+
+CREATE INDEX IF NOT EXISTS idx_hazo_files_path ON hazo_files (file_path);
+CREATE INDEX IF NOT EXISTS idx_hazo_files_storage ON hazo_files (storage_type);
+CREATE UNIQUE INDEX IF NOT EXISTS idx_hazo_files_path_storage ON hazo_files (file_path, storage_type);
+CREATE INDEX IF NOT EXISTS idx_hazo_files_hash ON hazo_files (file_hash);
+CREATE INDEX IF NOT EXISTS idx_hazo_files_status ON hazo_files (status);
+CREATE INDEX IF NOT EXISTS idx_hazo_files_scope ON hazo_files (scope_id);
+CREATE INDEX IF NOT EXISTS idx_hazo_files_ref_count ON hazo_files (ref_count);
+CREATE INDEX IF NOT EXISTS idx_hazo_files_deleted ON hazo_files (deleted_at);
+CREATE INDEX IF NOT EXISTS idx_hazo_files_content_tag ON hazo_files (content_tag);
+```
+
+### `hazo_files_naming` Table
+
+Required only if you use `NamingConventionService` to persist saved naming rules.
+
+#### PostgreSQL
+
+```sql
+CREATE TABLE IF NOT EXISTS hazo_files_naming (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  scope_id UUID,
+  naming_title TEXT NOT NULL,
+  naming_type TEXT NOT NULL CHECK(naming_type IN ('file', 'folder', 'both')),
+  naming_value TEXT NOT NULL,
+  created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
+  changed_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
+  variables TEXT DEFAULT '[]'
+);
+
+CREATE INDEX IF NOT EXISTS idx_hazo_files_naming_scope ON hazo_files_naming (scope_id);
+CREATE INDEX IF NOT EXISTS idx_hazo_files_naming_type ON hazo_files_naming (naming_type);
+```
+
+#### SQLite
+
+```sql
+CREATE TABLE IF NOT EXISTS hazo_files_naming (
+  id TEXT PRIMARY KEY,
+  scope_id TEXT,
+  naming_title TEXT NOT NULL,
+  naming_type TEXT NOT NULL CHECK(naming_type IN ('file', 'folder', 'both')),
+  naming_value TEXT NOT NULL,
+  created_at TEXT NOT NULL,
+  changed_at TEXT NOT NULL,
+  variables TEXT DEFAULT '[]'
+);
+
+CREATE INDEX IF NOT EXISTS idx_hazo_files_naming_scope ON hazo_files_naming (scope_id);
+CREATE INDEX IF NOT EXISTS idx_hazo_files_naming_type ON hazo_files_naming (naming_type);
+```
+
+### Programmatic Setup
+
+The same DDL is available as exported constants so you can run it from your app's startup or migration script without hand-copying SQL:
+
+```typescript
+import {
+  HAZO_FILES_TABLE_SCHEMA,
+  HAZO_FILES_NAMING_TABLE_SCHEMA,
+} from 'hazo_files';
+
+// Pick 'sqlite' or 'postgres'
+const dbType: 'sqlite' | 'postgres' = 'sqlite';
+
+// Create hazo_files table
+await db.run(HAZO_FILES_TABLE_SCHEMA[dbType].ddl);
+for (const idx of HAZO_FILES_TABLE_SCHEMA[dbType].indexes) {
+  await db.run(idx);
+}
+
+// Create hazo_files_naming table (only if using NamingConventionService)
+await db.run(HAZO_FILES_NAMING_TABLE_SCHEMA[dbType].ddl);
+for (const idx of HAZO_FILES_NAMING_TABLE_SCHEMA[dbType].indexes) {
+  await db.run(idx);
+}
+```
+
+For PostgreSQL, swap `db.run(...)` for `client.query(...)`.
+
+To use a custom table name, see `getSchemaForTable(name, dbType)` and `getNamingSchemaForTable(name, dbType)`.
+
+### Upgrading Existing Tables
+
+If you already have a pre-V2 or pre-V3 `hazo_files` table, see [Database Migration (Existing Databases)](#database-migration-existing-databases) and [V3 Database Migration](#v3-database-migration) for the `ALTER TABLE` scripts and migration helpers.
+
 ## UI Components
 
 ### FileBrowser Component

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hazo_files",
-  "version": "1.4.6",
+  "version": "1.4.7",
   "description": "File management including integration to cloud files",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -73,16 +73,16 @@
     "@dnd-kit/sortable": "^10.0.0",
     "@dnd-kit/utilities": "^3.2.2",
     "@types/ini": "^4.1.1",
-    "@types/node": "^20.10.0",
-    "@types/react": "^18.2.45",
-    "@types/react-dom": "^18.2.18",
+    "@types/node": "^20.14.10",
+    "@types/react": "^18.3.3",
+    "@types/react-dom": "^18.3.0",
     "dropbox": "^10.34.0",
     "googleapis": "^140.0.1",
     "hazo_llm_api": "^1.2.7",
     "react": "^18.2.0",
     "react-dom": "^18.2.0",
     "tsup": "^8.0.1",
-    "typescript": "^5.3.3",
+    "typescript": "^5.7.2",
     "vitest": "^4.0.15",
     "xxhash-wasm": "^1.1.0"
   },
@@ -92,10 +92,10 @@
     "@dnd-kit/utilities": "^3.0.0",
     "dropbox": "^10.0.0",
     "googleapis": "^140.0.0",
-    "hazo_connect": ">=2.0.0",
-    "hazo_debug": ">=1.0.0",
-    "hazo_llm_api": ">=1.0.0",
-    "hazo_logs": ">=1.0.0",
+    "hazo_connect": "^2.4.0",
+    "hazo_debug": "^2.0.0",
+    "hazo_llm_api": "^1.2.0",
+    "hazo_logs": "^1.0.13",
     "react": "^18.0.0",
     "react-dom": "^18.0.0",
     "server-only": ">=0.0.1",