@soulcraft/brainy 5.2.1 → 5.3.1

package/dist/versioning/VersioningAPI.d.ts

@@ -0,0 +1,347 @@
+/**
+ * VersioningAPI - Public API for Entity Versioning (v5.3.0)
+ *
+ * User-friendly wrapper around VersionManager with:
+ * - Clean, simple API
+ * - Smart defaults
+ * - Error handling
+ * - Type safety
+ *
+ * Usage:
+ *   const version = await brain.versions.save('entity-123', { tag: 'v1.0' })
+ *   const versions = await brain.versions.list('entity-123')
+ *   await brain.versions.restore('entity-123', 5)
+ *   const diff = await brain.versions.compare('entity-123', 2, 5)
+ *
+ * NO MOCKS - Production implementation
+ */
+import type { EntityVersion, SaveVersionOptions, RestoreOptions, PruneOptions, VersionQuery } from './VersionManager.js';
+import type { VersionDiff } from './VersionDiff.js';
+/**
+ * VersioningAPI - User-friendly versioning interface
+ */
+export declare class VersioningAPI {
+    private manager;
+    private brain;
+    constructor(brain: any);
+    /**
+     * Save current state of entity as a new version
+     *
+     * Creates a version snapshot of the current entity state.
+     * Automatically handles deduplication - if content hasn't changed,
+     * returns the last version instead of creating a duplicate.
+     *
+     * @param entityId Entity ID to version
+     * @param options Save options
+     * @returns Created (or existing) version metadata
+     *
+     * @example
+     * ```typescript
+     * // Simple save
+     * const version = await brain.versions.save('user-123')
+     *
+     * // Save with tag and description
+     * const version = await brain.versions.save('user-123', {
+     *   tag: 'v1.0',
+     *   description: 'Initial release',
+     *   author: 'alice'
+     * })
+     *
+     * // Save and create commit
+     * const version = await brain.versions.save('user-123', {
+     *   tag: 'milestone-1',
+     *   createCommit: true,
+     *   commitMessage: 'Milestone 1 complete'
+     * })
+     * ```
+     */
+    save(entityId: string, options?: SaveVersionOptions): Promise<EntityVersion>;
+    /**
+     * List all versions of an entity
+     *
+     * Returns versions sorted by version number (newest first).
+     * Supports filtering by tag, date range, and pagination.
+     *
+     * @param entityId Entity ID
+     * @param options Query options
+     * @returns List of versions (newest first)
+     *
+     * @example
+     * ```typescript
+     * // Get all versions
+     * const versions = await brain.versions.list('user-123')
+     *
+     * // Get last 10 versions
+     * const recent = await brain.versions.list('user-123', { limit: 10 })
+     *
+     * // Get tagged versions
+     * const tagged = await brain.versions.list('user-123', { tag: 'v*' })
+     *
+     * // Get versions from last 30 days
+     * const recent = await brain.versions.list('user-123', {
+     *   startDate: Date.now() - 30 * 24 * 60 * 60 * 1000
+     * })
+     * ```
+     */
+    list(entityId: string, options?: Partial<VersionQuery>): Promise<EntityVersion[]>;
+    /**
+     * Get specific version of an entity
+     *
+     * @param entityId Entity ID
+     * @param version Version number (1-indexed)
+     * @returns Version metadata or null if not found
+     *
+     * @example
+     * ```typescript
+     * const version = await brain.versions.getVersion('user-123', 5)
+     * if (version) {
+     *   console.log(`Version ${version.version} created at ${new Date(version.timestamp)}`)
+     * }
+     * ```
+     */
+    getVersion(entityId: string, version: number): Promise<EntityVersion | null>;
+    /**
+     * Get version by tag
+     *
+     * @param entityId Entity ID
+     * @param tag Version tag
+     * @returns Version metadata or null if not found
+     *
+     * @example
+     * ```typescript
+     * const version = await brain.versions.getVersionByTag('user-123', 'v1.0')
+     * ```
+     */
+    getVersionByTag(entityId: string, tag: string): Promise<EntityVersion | null>;
+    /**
+     * Get latest version of an entity
+     *
+     * @param entityId Entity ID
+     * @returns Latest version or null if no versions exist
+     *
+     * @example
+     * ```typescript
+     * const latest = await brain.versions.getLatest('user-123')
+     * ```
+     */
+    getLatest(entityId: string): Promise<EntityVersion | null>;
+    /**
+     * Get version content without restoring
+     *
+     * Allows you to preview version data without modifying the current entity.
+     *
+     * @param entityId Entity ID
+     * @param version Version number or tag
+     * @returns Version content
+     *
+     * @example
+     * ```typescript
+     * // Preview version 5 without restoring
+     * const oldData = await brain.versions.getContent('user-123', 5)
+     * console.log('Version 5 had name:', oldData.name)
+     *
+     * // Compare with current
+     * const current = await brain.getNounMetadata('user-123')
+     * console.log('Current name:', current.name)
+     * ```
+     */
+    getContent(entityId: string, version: number | string): Promise<any>;
+    /**
+     * Restore entity to a specific version
+     *
+     * Overwrites current entity state with the specified version.
+     * Optionally creates a snapshot before restoring for undo capability.
+     *
+     * @param entityId Entity ID
+     * @param version Version number or tag to restore to
+     * @param options Restore options
+     * @returns Restored version metadata
+     *
+     * @example
+     * ```typescript
+     * // Simple restore
+     * await brain.versions.restore('user-123', 5)
+     *
+     * // Restore with safety snapshot
+     * await brain.versions.restore('user-123', 5, {
+     *   createSnapshot: true,
+     *   snapshotTag: 'before-restore'
+     * })
+     *
+     * // Restore by tag
+     * await brain.versions.restore('user-123', 'v1.0')
+     * ```
+     */
+    restore(entityId: string, version: number | string, options?: RestoreOptions): Promise<EntityVersion>;
+    /**
+     * Compare two versions of an entity
+     *
+     * Generates a deep diff showing added, removed, modified, and type-changed fields.
+     *
+     * @param entityId Entity ID
+     * @param fromVersion Version number or tag (older)
+     * @param toVersion Version number or tag (newer)
+     * @returns Diff between versions
+     *
+     * @example
+     * ```typescript
+     * // Compare version 2 to version 5
+     * const diff = await brain.versions.compare('user-123', 2, 5)
+     *
+     * console.log(`Added fields: ${diff.added.length}`)
+     * console.log(`Removed fields: ${diff.removed.length}`)
+     * console.log(`Modified fields: ${diff.modified.length}`)
+     *
+     * // Print human-readable diff
+     * import { formatDiff } from './VersionDiff.js'
+     * console.log(formatDiff(diff))
+     * ```
+     */
+    compare(entityId: string, fromVersion: number | string, toVersion: number | string): Promise<VersionDiff>;
+    /**
+     * Prune old versions based on retention policy
+     *
+     * Removes old versions while preserving recent and tagged versions.
+     * Use dryRun to preview what would be deleted without actually deleting.
+     *
+     * @param entityId Entity ID (or '*' for all entities - NOT IMPLEMENTED YET)
+     * @param options Prune options
+     * @returns Count of deleted and kept versions
+     *
+     * @example
+     * ```typescript
+     * // Keep last 10 versions, delete rest
+     * const result = await brain.versions.prune('user-123', {
+     *   keepRecent: 10
+     * })
+     * console.log(`Deleted ${result.deleted} versions`)
+     *
+     * // Keep last 30 days, preserve tagged versions
+     * const result = await brain.versions.prune('user-123', {
+     *   keepAfter: Date.now() - 30 * 24 * 60 * 60 * 1000,
+     *   keepTagged: true
+     * })
+     *
+     * // Dry run - see what would be deleted
+     * const result = await brain.versions.prune('user-123', {
+     *   keepRecent: 5,
+     *   dryRun: true
+     * })
+     * console.log(`Would delete ${result.deleted} versions`)
+     * ```
+     */
+    prune(entityId: string, options: PruneOptions): Promise<{
+        deleted: number;
+        kept: number;
+    }>;
+    /**
+     * Get version count for an entity
+     *
+     * @param entityId Entity ID
+     * @returns Number of versions
+     *
+     * @example
+     * ```typescript
+     * const count = await brain.versions.count('user-123')
+     * console.log(`Entity has ${count} versions`)
+     * ```
+     */
+    count(entityId: string): Promise<number>;
+    /**
+     * Check if entity has any versions
+     *
+     * @param entityId Entity ID
+     * @returns True if entity has versions
+     *
+     * @example
+     * ```typescript
+     * if (await brain.versions.hasVersions('user-123')) {
+     *   console.log('Entity is versioned')
+     * }
+     * ```
+     */
+    hasVersions(entityId: string): Promise<boolean>;
+    /**
+     * Clear all versions for an entity
+     *
+     * WARNING: This permanently deletes all version history!
+     *
+     * @param entityId Entity ID
+     * @returns Number of versions deleted
+     *
+     * @example
+     * ```typescript
+     * const deleted = await brain.versions.clear('user-123')
+     * console.log(`Deleted ${deleted} versions`)
+     * ```
+     */
+    clear(entityId: string): Promise<number>;
+    /**
+     * Quick save with auto-generated tag
+     *
+     * Generates tag in format: 'auto-{timestamp}'
+     *
+     * @param entityId Entity ID
+     * @param description Optional description
+     * @returns Created version
+     */
+    quickSave(entityId: string, description?: string): Promise<EntityVersion>;
+    /**
+     * Undo last change (restore to previous version)
+     *
+     * Safely restores to previous version with automatic snapshot.
+     *
+     * @param entityId Entity ID
+     * @returns Restored version metadata
+     */
+    undo(entityId: string): Promise<EntityVersion | null>;
+    /**
+     * Get version history summary
+     *
+     * @param entityId Entity ID
+     * @returns Summary statistics
+     */
+    history(entityId: string): Promise<{
+        total: number;
+        oldest?: EntityVersion;
+        newest?: EntityVersion;
+        tagged: number;
+        branches: string[];
+    }>;
+    /**
+     * Revert to previous version (alias for undo with better semantics)
+     *
+     * Restores entity to the previous version with automatic safety snapshot.
+     *
+     * @param entityId Entity ID
+     * @returns Restored version or null if not possible
+     *
+     * @example
+     * ```typescript
+     * // Made a mistake? Revert!
+     * await brain.update('user-123', { name: 'Wrong Name' })
+     * await brain.versions.revert('user-123')  // Back to previous state
+     * ```
+     */
+    revert(entityId: string): Promise<EntityVersion | null>;
+    /**
+     * Tag an existing version
+     *
+     * Updates the tag of an existing version.
+     * Note: This creates a new version with the tag, not modifying the existing one.
+     *
+     * @param entityId Entity ID
+     * @param version Version number
+     * @param tag New tag
+     * @returns Updated version
+     */
+    tag(entityId: string, version: number, tag: string): Promise<EntityVersion>;
+    /**
+     * Get diff between entity's current state and a version
+     *
+     * @param entityId Entity ID
+     * @param version Version to compare against
+     * @returns Diff showing changes
+     */
+    diffWithCurrent(entityId: string, version: number | string): Promise<VersionDiff>;
+}