feat(watcher): add polling-based BucketWatcher to detect add/modify/delete events and expose RxJS Observable and EventEmitter APIs

ts/classes.bucket.ts

@@ -8,6 +8,7 @@ import { Directory } from './classes.directory.js';
 import { File } from './classes.file.js';
 import { Trash } from './classes.trash.js';
 import { ListCursor, type IListCursorOptions } from './classes.listcursor.js';
+import { BucketWatcher } from './classes.watcher.js';
 
 /**
  * The bucket class exposes the basic functionality of a bucket.
@@ -568,6 +569,23 @@ export class Bucket {
     return new ListCursor(this, prefix, options);
   }
 
+  /**
+   * Create a watcher for monitoring bucket changes (add/modify/delete)
+   * @param options - Watcher options (prefix, pollIntervalMs, etc.)
+   * @returns BucketWatcher instance
+   * @example
+   * ```ts
+   * const watcher = bucket.createWatcher({ prefix: 'uploads/', pollIntervalMs: 3000 });
+   * watcher.changeSubject.subscribe((change) => console.log('Change:', change));
+   * await watcher.start();
+   * // ... later
+   * await watcher.stop();
+   * ```
+   */
+  public createWatcher(options?: interfaces.IBucketWatcherOptions): BucketWatcher {
+    return new BucketWatcher(this, options);
+  }
+
   // ==========================================
   // High-Level Listing Helpers (Phase 2)
   // ==========================================