hazo_files 1.5.2 → 2.0.0

package/dist/index.d.ts

@@ -187,6 +187,10 @@ interface FileMetadataInput {
     original_filename?: string;
     /** Content tag classifying the document type (V3) */
     content_tag?: string;
+    /** Actor UUID who performed this mutation (V4) */
+    changed_by?: string;
+    /** Source URL when file was imported via importFromUrl (V4) */
+    source_url?: string;
 }
 /**
  * Input for updating an existing metadata record
@@ -433,6 +437,10 @@ interface FileMetadataRecordV2 extends FileMetadataRecord {
     deleted_at?: string | null;
     /** Content tag classifying the document type (V3) */
     content_tag?: string | null;
+    /** Actor UUID who last mutated this record (V4 — migration 004) */
+    changed_by?: string | null;
+    /** Source URL when file was imported via importFromUrl (V4 — migration 005) */
+    source_url?: string | null;
 }
 /**
  * Options for adding a reference to a file
@@ -770,8 +778,9 @@ declare class FileMetadataService {
     recordAccess(path: string, storageType: StorageProvider): Promise<boolean>;
     /**
      * Record a file deletion
+     * changedBy is accepted for API consistency but not written (record is deleted)
      */
-    recordDelete(path: string, storageType: StorageProvider): Promise<boolean>;
+    recordDelete(path: string, storageType: StorageProvider, _changedBy?: string): Promise<boolean>;
     /**
      * Record a directory deletion (recursive)
      */
@@ -779,11 +788,11 @@ declare class FileMetadataService {
     /**
      * Record a file or folder move
      */
-    recordMove(sourcePath: string, destinationPath: string, storageType: StorageProvider): Promise<boolean>;
+    recordMove(sourcePath: string, destinationPath: string, storageType: StorageProvider, changedBy?: string): Promise<boolean>;
     /**
      * Record a file or folder rename
      */
-    recordRename(path: string, newName: string, storageType: StorageProvider): Promise<boolean>;
+    recordRename(path: string, newName: string, storageType: StorageProvider, changedBy?: string): Promise<boolean>;
     /**
      * Find a record by path and storage type
      */
@@ -887,9 +896,9 @@ declare class FileMetadataService {
      */
     softDelete(fileId: string): Promise<boolean>;
     /**
-     * Update specific V2 fields on a record
+     * Update specific V2/V4 fields on a record
      */
-    updateFields(fileId: string, fields: Partial<Pick<FileMetadataRecordV2, 'scope_id' | 'uploaded_by' | 'original_filename' | 'storage_verified_at' | 'status' | 'content_tag'>>): Promise<boolean>;
+    updateFields(fileId: string, fields: Partial<Pick<FileMetadataRecordV2, 'scope_id' | 'uploaded_by' | 'original_filename' | 'storage_verified_at' | 'status' | 'content_tag' | 'changed_by' | 'source_url'>>): Promise<boolean>;
     /**
      * Find orphaned files (zero references)
      */
@@ -1053,6 +1062,138 @@ declare function createFileManager(options?: FileManagerOptions): FileManager;
  */
 declare function createInitializedFileManager(options?: FileManagerOptions): Promise<FileManager>;
 
+/**
+ * Quota Service
+ * Per-scope opt-in quota tracking with threshold callbacks.
+ *
+ * A scope without a hazo_file_quotas row has no quota and uploads succeed (fail-open).
+ */
+/**
+ * Quota status for a scope
+ */
+interface QuotaStatus {
+    scopeId: string;
+    byteLimit: number;
+    byteUsed: number;
+    percentUsed: number;
+}
+/**
+ * Event emitted when usage crosses a configured threshold band
+ */
+interface QuotaThresholdEvent {
+    scopeId: string;
+    /** Fractional threshold crossed, e.g. 0.80 or 0.95 */
+    percent: number;
+    bytesUsed: number;
+    byteLimit: number;
+}
+/**
+ * Raw row shape from hazo_file_quotas table
+ */
+interface QuotaRow {
+    scope_id: string;
+    byte_limit: number;
+    byte_used: number;
+    updated_at: string;
+    [key: string]: unknown;
+}
+/**
+ * Minimal interface for the quota CRUD service (hazo_connect compatible)
+ */
+interface QuotaCrudServiceLike {
+    findBy(criteria: Record<string, unknown>): Promise<QuotaRow[]>;
+    findOneBy(criteria: Record<string, unknown>): Promise<QuotaRow | null>;
+    insert(data: Partial<QuotaRow> | Partial<QuotaRow>[]): Promise<QuotaRow[]>;
+    updateById(id: unknown, patch: Partial<QuotaRow>): Promise<QuotaRow[]>;
+    list(configure?: (qb: unknown) => unknown): Promise<QuotaRow[]>;
+}
+/**
+ * Options for QuotaService
+ */
+interface QuotaServiceOptions {
+    /** hazo_connect CRUD service pointed at hazo_file_quotas table */
+    crudService: QuotaCrudServiceLike;
+    /** Callback fired when usage crosses a threshold band */
+    onThreshold?: (event: QuotaThresholdEvent) => void;
+    /** Fractional threshold bands (default: [0.80, 0.95]) */
+    bands?: number[];
+    /** Logger for diagnostics */
+    logger?: {
+        debug?(message: string, data?: Record<string, unknown>): void;
+        warn?(message: string, data?: Record<string, unknown>): void;
+        error?(message: string, data?: Record<string, unknown>): void;
+    };
+}
+/**
+ * Per-scope opt-in quota tracking.
+ *
+ * Fail-open: a scope without a quota row has no quota and all uploads succeed.
+ */
+declare class QuotaService {
+    private crud;
+    private onThreshold?;
+    private bands;
+    private logger?;
+    constructor(opts: QuotaServiceOptions);
+    /**
+     * Get quota status for a scope.
+     * Returns null if no quota row exists (fail-open = no quota set).
+     */
+    getQuota(scopeId: string): Promise<QuotaStatus | null>;
+    /**
+     * Set (or update) the byte limit for a scope.
+     * Creates a quota row if one does not exist (with byte_used = 0).
+     * Returns the current stored status after upsert.
+     *
+     * @note This method does NOT auto-reconcile byte_used via a SUM query —
+     *   it simply upserts the limit and returns the stored row. To reconcile
+     *   byte_used against actual file sizes, call recomputeQuota() separately
+     *   after a SUM(file_size) query on hazo_files for the scope.
+     */
+    setQuotaLimit(scopeId: string, bytes: number): Promise<QuotaStatus>;
+    /**
+     * Recompute byteUsed by reading the current row.
+     * (Full reconciliation against actual file sizes should be done externally
+     * via a SUM query on hazo_files; this method just returns the stored state.)
+     */
+    recomputeQuota(scopeId: string): Promise<QuotaStatus>;
+    /**
+     * Pre-upload check ONLY — does NOT increment.
+     * Throws QuotaExceededError if the upload would exceed the limit.
+     * If no quota row exists for the scope, succeeds silently (fail-open).
+     *
+     * Use this before the upload, then call incrementUsage after confirmed success.
+     * This prevents quota inflation when an upload fails mid-stream.
+     */
+    checkQuota(scopeId: string, deltaBytes: number): Promise<void>;
+    /**
+     * Pre-upload check and increment (atomic). Throws QuotaExceededError if the upload
+     * would exceed the limit. If no quota row exists, succeeds silently (fail-open).
+     * Also fires threshold callbacks for any bands crossed by the new usage.
+     *
+     * @deprecated Prefer checkQuota() before upload + incrementUsage() after success.
+     *   checkAndIncrement() increments before the upload completes; if the upload
+     *   subsequently fails the quota is inflated with no rollback.
+     */
+    checkAndIncrement(scopeId: string, deltaBytes: number): Promise<void>;
+    /**
+     * Decrement usage (call after soft-delete or hard-delete).
+     * Clamps to zero; no-ops if no quota row.
+     */
+    decrementUsage(scopeId: string, deltaBytes: number): Promise<void>;
+    /**
+     * Increment usage manually (admin override).
+     * Does NOT throw on exceeded quota — admin is explicitly bypassing.
+     */
+    incrementUsage(scopeId: string, deltaBytes: number): Promise<void>;
+    /**
+     * Fire threshold callbacks for all bands crossed going from prevUsed → newUsed.
+     * Bands are sorted ascending so callbacks fire in order (80% before 95%).
+     */
+    private fireThresholdCallbacks;
+    private rowToStatus;
+}
+
 /**
  * Tracked File Manager
  * Extends FileManager to add database tracking of file operations
@@ -1068,6 +1209,10 @@ interface TrackedFileManagerFullOptions extends FileManagerOptions {
     tracking?: DatabaseTrackingConfig;
     /** Logger for structured file operation logging */
     logger?: MetadataLogger;
+    /** Optional quota service for per-scope upload limits */
+    quotaService?: QuotaService;
+    /** SSRF allowlist passed to importFromUrl (host strings) */
+    ssrfAllowlist?: string[];
 }
 /**
  * Extended upload options with hash tracking
@@ -1081,6 +1226,10 @@ interface TrackedUploadOptions extends UploadOptions {
      * Set to true when you need to immediately query/update the file record.
      */
     awaitRecording?: boolean;
+    /** Actor ID (UUID) to record in uploaded_by and changed_by columns */
+    actor_id?: string;
+    /** Scope ID for quota tracking and organizational grouping */
+    scope_id?: string;
 }
 /**
  * TrackedFileManager - File manager with database tracking
@@ -1091,6 +1240,8 @@ interface TrackedUploadOptions extends UploadOptions {
 declare class TrackedFileManager extends FileManager {
     private metadataService;
     private trackingConfig;
+    private quotaService;
+    private ssrfAllowlist;
     constructor(options?: TrackedFileManagerFullOptions);
     /**
      * Check if tracking is enabled and service is available
@@ -1120,19 +1271,27 @@ declare class TrackedFileManager extends FileManager {
     /**
      * Move a file or folder and update its path in the database
      */
-    moveItem(sourcePath: string, destinationPath: string, options?: MoveOptions): Promise<OperationResult<FileSystemItem>>;
+    moveItem(sourcePath: string, destinationPath: string, options?: MoveOptions & {
+        actor_id?: string;
+    }): Promise<OperationResult<FileSystemItem>>;
     /**
      * Delete a file and remove its record from the database
      */
-    deleteFile(path: string): Promise<OperationResult>;
+    deleteFile(path: string, opts?: {
+        actor_id?: string;
+    }): Promise<OperationResult>;
     /**
      * Rename a file and update its record in the database
      */
-    renameFile(path: string, newName: string, options?: RenameOptions): Promise<OperationResult<FileItem>>;
+    renameFile(path: string, newName: string, options?: RenameOptions & {
+        actor_id?: string;
+    }): Promise<OperationResult<FileItem>>;
     /**
      * Rename a folder and update its record in the database
      */
-    renameFolder(path: string, newName: string, options?: RenameOptions): Promise<OperationResult<FolderItem>>;
+    renameFolder(path: string, newName: string, options?: RenameOptions & {
+        actor_id?: string;
+    }): Promise<OperationResult<FolderItem>>;
     /**
      * Write a file with string content and track it
      */
@@ -1211,8 +1370,33 @@ declare class TrackedFileManager extends FileManager {
     getFilesById(fileIds: string[]): Promise<FileWithStatus[]>;
     /**
      * Soft-delete a file (marks as soft_deleted, does not remove physical file)
+     * Also decrements quota usage if quotaService is configured.
+     */
+    softDeleteFile(fileId: string, opts?: {
+        actor_id?: string;
+    }): Promise<boolean>;
+    /**
+     * Get quota status for a scope.
+     * Returns null if no quota is configured (fail-open).
+     */
+    getQuota(scopeId: string): Promise<QuotaStatus | null>;
+    /**
+     * Set or update the byte limit for a scope.
+     * Creates a quota row if one does not exist.
+     */
+    setQuotaLimit(scopeId: string, bytes: number): Promise<QuotaStatus | null>;
+    /**
+     * Recompute and return the quota status for a scope.
      */
-    softDeleteFile(fileId: string): Promise<boolean>;
+    recomputeQuota(scopeId: string): Promise<QuotaStatus | null>;
+    /**
+     * Increment usage for a scope (admin override — does not throw on exceeded quota).
+     */
+    incrementQuotaUsage(scopeId: string, deltaBytes: number): Promise<void>;
+    /**
+     * Decrement usage for a scope (e.g. after manual cleanup).
+     */
+    decrementQuotaUsage(scopeId: string, deltaBytes: number): Promise<void>;
     /**
      * Find orphaned files (files with zero references)
      */
@@ -1235,6 +1419,31 @@ declare class TrackedFileManager extends FileManager {
         file_id?: string;
         ref_id?: string;
     }>>;
+    /**
+     * Import a file from a URL into virtual storage.
+     *
+     * Uses hazo_secure/fetch for SSRF protection (optional peer dependency).
+     * Streams the response to a temp file, counting bytes live.
+     * On cap exceeded: aborts, deletes temp file, throws ImportSizeCapError.
+     * On success: uploads to virtualPath, sets source_url in DB record.
+     *
+     * @param url - URL to fetch
+     * @param virtualPath - Destination virtual path in storage
+     * @param opts.referrer - Optional Referer header to send
+     * @param opts.maxBytes - Maximum response size in bytes (default: 50MB)
+     * @param opts.actor_id - Actor UUID to record in uploaded_by / changed_by
+     */
+    importFromUrl(url: string, virtualPath: string, opts?: {
+        referrer?: string;
+        maxBytes?: number;
+        actor_id?: string;
+        /** Scope ID for quota checking and tracking. If provided, quota is checked before upload. */
+        scope_id?: string;
+    }): Promise<OperationResult<{
+        virtualPath: string;
+        size: number;
+        sourceUrl: string;
+    }>>;
 }
 /**
  * Create a new TrackedFileManager instance
@@ -1821,6 +2030,10 @@ interface HazoFilesColumnDefinitions {
     original_filename: 'TEXT';
     /** Content tag classifying the document type (V3) */
     content_tag: 'TEXT';
+    /** UUID of the actor who last mutated this record (V4 — migration 004) */
+    changed_by: 'TEXT' | 'UUID';
+    /** Source URL when file was imported via importFromUrl (V4 — migration 005) */
+    source_url: 'TEXT';
 }
 /**
  * Schema definition for a specific database type