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

ts/interfaces.ts

@@ -3,4 +3,55 @@ import type { Directory } from "./classes.directory.js";
 export interface IPathDecriptor {
   path?: string;
   directory?: Directory;
+}
+
+// ================================
+// Bucket Watcher Interfaces
+// ================================
+
+/**
+ * Internal state tracking for an S3 object
+ */
+export interface IS3ObjectState {
+  key: string;
+  etag: string;
+  size: number;
+  lastModified: Date;
+}
+
+/**
+ * Change event emitted by BucketWatcher
+ */
+export interface IS3ChangeEvent {
+  type: 'add' | 'modify' | 'delete';
+  key: string;
+  size?: number;
+  etag?: string;
+  lastModified?: Date;
+  bucket: string;
+}
+
+/**
+ * Watcher mode - 'poll' is the default, 'websocket' reserved for future implementation
+ */
+export type TBucketWatcherMode = 'poll' | 'websocket';
+
+/**
+ * Options for creating a BucketWatcher
+ */
+export interface IBucketWatcherOptions {
+  /** Watcher mode: 'poll' (default) or 'websocket' (future) */
+  mode?: TBucketWatcherMode;
+  /** Prefix to filter objects (default: '' for all objects) */
+  prefix?: string;
+  /** Polling interval in milliseconds (default: 5000, poll mode only) */
+  pollIntervalMs?: number;
+  /** Optional RxJS buffering time in milliseconds */
+  bufferTimeMs?: number;
+  /** Emit initial state as 'add' events (default: false) */
+  includeInitial?: boolean;
+  /** Page size for listing operations (default: 1000) */
+  pageSize?: number;
+  // Future websocket options will be added here
+  // websocketUrl?: string;
 }