@soulcraft/brainy 1.5.0 → 2.0.1

package/dist/augmentations/storageAugmentation.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Storage Augmentation Base Classes
+ *
+ * Unifies storage adapters and augmentations into a single system.
+ * All storage backends are now augmentations for consistency and extensibility.
+ */
+import { BaseAugmentation, BrainyAugmentation, AugmentationContext } from './brainyAugmentation.js';
+import { StorageAdapter } from '../coreTypes.js';
+/**
+ * Base class for all storage augmentations
+ * Provides the storage adapter to the brain during initialization
+ */
+export declare abstract class StorageAugmentation extends BaseAugmentation implements BrainyAugmentation {
+    readonly timing: "replace";
+    operations: ("storage")[];
+    readonly priority = 100;
+    protected storageAdapter: StorageAdapter | null;
+    constructor();
+    /**
+     * Provide the storage adapter before full initialization
+     * This is called during the storage resolution phase
+     */
+    abstract provideStorage(): Promise<StorageAdapter>;
+    /**
+     * Initialize the augmentation with context
+     * Called after storage has been resolved
+     */
+    initialize(context: AugmentationContext): Promise<void>;
+    /**
+     * Execute storage operations
+     * For storage augmentations, this replaces the default storage
+     */
+    execute<T = any>(operation: string, params: any, next: () => Promise<T>): Promise<T>;
+    /**
+     * Shutdown and cleanup
+     */
+    shutdown(): Promise<void>;
+}
+/**
+ * Dynamic storage augmentation that wraps any storage adapter
+ * Used for backward compatibility and zero-config
+ */
+export declare class DynamicStorageAugmentation extends StorageAugmentation {
+    private adapter;
+    readonly name = "dynamic-storage";
+    constructor(adapter: StorageAdapter);
+    provideStorage(): Promise<StorageAdapter>;
+    protected onInitialize(): Promise<void>;
+}
+/**
+ * Create a storage augmentation from configuration
+ * Maintains backward compatibility with existing storage config
+ */
+export declare function createStorageAugmentationFromConfig(config: any): Promise<StorageAugmentation | null>;

package/dist/augmentations/storageAugmentation.js

@@ -0,0 +1,93 @@
+/**
+ * Storage Augmentation Base Classes
+ *
+ * Unifies storage adapters and augmentations into a single system.
+ * All storage backends are now augmentations for consistency and extensibility.
+ */
+import { BaseAugmentation } from './brainyAugmentation.js';
+/**
+ * Base class for all storage augmentations
+ * Provides the storage adapter to the brain during initialization
+ */
+export class StorageAugmentation extends BaseAugmentation {
+    // Storage augmentations must provide their name via readonly property
+    constructor() {
+        super();
+        this.timing = 'replace';
+        this.operations = ['storage']; // Make mutable for TypeScript compatibility
+        this.priority = 100; // High priority for storage
+        this.storageAdapter = null;
+    }
+    /**
+     * Initialize the augmentation with context
+     * Called after storage has been resolved
+     */
+    async initialize(context) {
+        await super.initialize(context);
+        // Storage adapter should already be provided
+        if (!this.storageAdapter) {
+            this.storageAdapter = await this.provideStorage();
+        }
+    }
+    /**
+     * Execute storage operations
+     * For storage augmentations, this replaces the default storage
+     */
+    async execute(operation, params, next) {
+        if (operation === 'storage') {
+            // Return our storage adapter
+            return this.storageAdapter;
+        }
+        // Pass through all other operations
+        return next();
+    }
+    /**
+     * Shutdown and cleanup
+     */
+    async shutdown() {
+        // Cleanup storage adapter if needed
+        if (this.storageAdapter && typeof this.storageAdapter.close === 'function') {
+            await this.storageAdapter.close();
+        }
+        await super.shutdown();
+    }
+}
+/**
+ * Dynamic storage augmentation that wraps any storage adapter
+ * Used for backward compatibility and zero-config
+ */
+export class DynamicStorageAugmentation extends StorageAugmentation {
+    constructor(adapter) {
+        super();
+        this.adapter = adapter;
+        this.name = 'dynamic-storage';
+        this.storageAdapter = adapter;
+    }
+    async provideStorage() {
+        return this.adapter;
+    }
+    async onInitialize() {
+        // Adapter is already provided in constructor
+        await this.adapter.init();
+        this.log(`${this.name} initialized`);
+    }
+}
+/**
+ * Create a storage augmentation from configuration
+ * Maintains backward compatibility with existing storage config
+ */
+export async function createStorageAugmentationFromConfig(config) {
+    // Import storage factory dynamically to avoid circular deps
+    const { createStorage } = await import('../storage/storageFactory.js');
+    try {
+        // Create storage adapter from config
+        const adapter = await createStorage(config);
+        // Wrap in augmentation
+        return new DynamicStorageAugmentation(adapter);
+    }
+    catch (error) {
+        console.warn('Failed to create storage augmentation from config:', error);
+        return null;
+    }
+}
+//# sourceMappingURL=storageAugmentation.js.map

package/dist/augmentations/storageAugmentations.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Storage Augmentations - Concrete Implementations
+ *
+ * These augmentations provide different storage backends for Brainy.
+ * Each wraps an existing storage adapter for backward compatibility.
+ */
+import { StorageAugmentation } from './storageAugmentation.js';
+import { StorageAdapter } from '../coreTypes.js';
+/**
+ * Memory Storage Augmentation - Fast in-memory storage
+ */
+export declare class MemoryStorageAugmentation extends StorageAugmentation {
+    readonly name = "memory-storage";
+    constructor();
+    provideStorage(): Promise<StorageAdapter>;
+    protected onInitialize(): Promise<void>;
+}
+/**
+ * FileSystem Storage Augmentation - Node.js persistent storage
+ */
+export declare class FileSystemStorageAugmentation extends StorageAugmentation {
+    readonly name = "filesystem-storage";
+    private rootDirectory;
+    constructor(rootDirectory?: string);
+    provideStorage(): Promise<StorageAdapter>;
+    protected onInitialize(): Promise<void>;
+}
+/**
+ * OPFS Storage Augmentation - Browser persistent storage
+ */
+export declare class OPFSStorageAugmentation extends StorageAugmentation {
+    readonly name = "opfs-storage";
+    private requestPersistent;
+    constructor(requestPersistent?: boolean);
+    provideStorage(): Promise<StorageAdapter>;
+    protected onInitialize(): Promise<void>;
+}
+/**
+ * S3 Storage Augmentation - Amazon S3 cloud storage
+ */
+export declare class S3StorageAugmentation extends StorageAugmentation {
+    readonly name = "s3-storage";
+    private config;
+    constructor(config: {
+        bucketName: string;
+        region?: string;
+        accessKeyId: string;
+        secretAccessKey: string;
+        sessionToken?: string;
+        cacheConfig?: any;
+        operationConfig?: any;
+    });
+    provideStorage(): Promise<StorageAdapter>;
+    protected onInitialize(): Promise<void>;
+}
+/**
+ * R2 Storage Augmentation - Cloudflare R2 storage
+ */
+export declare class R2StorageAugmentation extends StorageAugmentation {
+    readonly name = "r2-storage";
+    private config;
+    constructor(config: {
+        bucketName: string;
+        accountId: string;
+        accessKeyId: string;
+        secretAccessKey: string;
+        cacheConfig?: any;
+    });
+    provideStorage(): Promise<StorageAdapter>;
+    protected onInitialize(): Promise<void>;
+}
+/**
+ * GCS Storage Augmentation - Google Cloud Storage
+ */
+export declare class GCSStorageAugmentation extends StorageAugmentation {
+    readonly name = "gcs-storage";
+    private config;
+    constructor(config: {
+        bucketName: string;
+        region?: string;
+        accessKeyId: string;
+        secretAccessKey: string;
+        endpoint?: string;
+        cacheConfig?: any;
+    });
+    provideStorage(): Promise<StorageAdapter>;
+    protected onInitialize(): Promise<void>;
+}
+/**
+ * Auto-select the best storage augmentation for the environment
+ * Maintains zero-config philosophy
+ */
+export declare function createAutoStorageAugmentation(options?: {
+    rootDirectory?: string;
+    requestPersistentStorage?: boolean;
+}): Promise<StorageAugmentation>;

package/dist/augmentations/storageAugmentations.js

@@ -0,0 +1,182 @@
+/**
+ * Storage Augmentations - Concrete Implementations
+ *
+ * These augmentations provide different storage backends for Brainy.
+ * Each wraps an existing storage adapter for backward compatibility.
+ */
+import { StorageAugmentation } from './storageAugmentation.js';
+import { MemoryStorage } from '../storage/adapters/memoryStorage.js';
+import { OPFSStorage } from '../storage/adapters/opfsStorage.js';
+import { S3CompatibleStorage, R2Storage } from '../storage/adapters/s3CompatibleStorage.js';
+/**
+ * Memory Storage Augmentation - Fast in-memory storage
+ */
+export class MemoryStorageAugmentation extends StorageAugmentation {
+    constructor() {
+        super();
+        this.name = 'memory-storage';
+    }
+    async provideStorage() {
+        const storage = new MemoryStorage();
+        this.storageAdapter = storage;
+        return storage;
+    }
+    async onInitialize() {
+        await this.storageAdapter.init();
+        this.log('Memory storage initialized');
+    }
+}
+/**
+ * FileSystem Storage Augmentation - Node.js persistent storage
+ */
+export class FileSystemStorageAugmentation extends StorageAugmentation {
+    constructor(rootDirectory = './brainy-data') {
+        super();
+        this.name = 'filesystem-storage';
+        this.rootDirectory = rootDirectory;
+    }
+    async provideStorage() {
+        try {
+            // Dynamically import for Node.js environments
+            const { FileSystemStorage } = await import('../storage/adapters/fileSystemStorage.js');
+            const storage = new FileSystemStorage(this.rootDirectory);
+            this.storageAdapter = storage;
+            return storage;
+        }
+        catch (error) {
+            this.log('FileSystemStorage not available, falling back to memory', 'warn');
+            // Fall back to memory storage
+            const storage = new MemoryStorage();
+            this.storageAdapter = storage;
+            return storage;
+        }
+    }
+    async onInitialize() {
+        await this.storageAdapter.init();
+        this.log(`FileSystem storage initialized at ${this.rootDirectory}`);
+    }
+}
+/**
+ * OPFS Storage Augmentation - Browser persistent storage
+ */
+export class OPFSStorageAugmentation extends StorageAugmentation {
+    constructor(requestPersistent = false) {
+        super();
+        this.name = 'opfs-storage';
+        this.requestPersistent = requestPersistent;
+    }
+    async provideStorage() {
+        const storage = new OPFSStorage();
+        if (!storage.isOPFSAvailable()) {
+            this.log('OPFS not available, falling back to memory', 'warn');
+            const memStorage = new MemoryStorage();
+            this.storageAdapter = memStorage;
+            return memStorage;
+        }
+        this.storageAdapter = storage;
+        return storage;
+    }
+    async onInitialize() {
+        await this.storageAdapter.init();
+        if (this.requestPersistent && this.storageAdapter instanceof OPFSStorage) {
+            const granted = await this.storageAdapter.requestPersistentStorage();
+            this.log(`Persistent storage ${granted ? 'granted' : 'denied'}`);
+        }
+        this.log('OPFS storage initialized');
+    }
+}
+/**
+ * S3 Storage Augmentation - Amazon S3 cloud storage
+ */
+export class S3StorageAugmentation extends StorageAugmentation {
+    constructor(config) {
+        super();
+        this.name = 's3-storage';
+        this.config = config;
+    }
+    async provideStorage() {
+        const storage = new S3CompatibleStorage({
+            ...this.config,
+            serviceType: 's3'
+        });
+        this.storageAdapter = storage;
+        return storage;
+    }
+    async onInitialize() {
+        await this.storageAdapter.init();
+        this.log(`S3 storage initialized with bucket ${this.config.bucketName}`);
+    }
+}
+/**
+ * R2 Storage Augmentation - Cloudflare R2 storage
+ */
+export class R2StorageAugmentation extends StorageAugmentation {
+    constructor(config) {
+        super();
+        this.name = 'r2-storage';
+        this.config = config;
+    }
+    async provideStorage() {
+        const storage = new R2Storage({
+            ...this.config,
+            serviceType: 'r2'
+        });
+        this.storageAdapter = storage;
+        return storage;
+    }
+    async onInitialize() {
+        await this.storageAdapter.init();
+        this.log(`R2 storage initialized with bucket ${this.config.bucketName}`);
+    }
+}
+/**
+ * GCS Storage Augmentation - Google Cloud Storage
+ */
+export class GCSStorageAugmentation extends StorageAugmentation {
+    constructor(config) {
+        super();
+        this.name = 'gcs-storage';
+        this.config = config;
+    }
+    async provideStorage() {
+        const storage = new S3CompatibleStorage({
+            ...this.config,
+            endpoint: this.config.endpoint || 'https://storage.googleapis.com',
+            serviceType: 'gcs'
+        });
+        this.storageAdapter = storage;
+        return storage;
+    }
+    async onInitialize() {
+        await this.storageAdapter.init();
+        this.log(`GCS storage initialized with bucket ${this.config.bucketName}`);
+    }
+}
+/**
+ * Auto-select the best storage augmentation for the environment
+ * Maintains zero-config philosophy
+ */
+export async function createAutoStorageAugmentation(options = {}) {
+    // Detect environment
+    const isNodeEnv = globalThis.__ENV__?.isNode || (typeof process !== 'undefined' &&
+        process.versions != null &&
+        process.versions.node != null);
+    if (isNodeEnv) {
+        // Node.js environment - use FileSystem
+        return new FileSystemStorageAugmentation(options.rootDirectory || './brainy-data');
+    }
+    else {
+        // Browser environment - try OPFS, fall back to memory
+        const opfsAug = new OPFSStorageAugmentation(options.requestPersistentStorage || false);
+        // Test if OPFS is available
+        const testStorage = new OPFSStorage();
+        if (testStorage.isOPFSAvailable()) {
+            return opfsAug;
+        }
+        else {
+            // Fall back to memory
+            return new MemoryStorageAugmentation();
+        }
+    }
+}
+//# sourceMappingURL=storageAugmentations.js.map

package/dist/augmentations/synapseAugmentation.d.ts

@@ -0,0 +1,156 @@
+/**
+ * Base Synapse Augmentation
+ *
+ * Synapses are special augmentations that provide bidirectional data sync
+ * with external platforms (Notion, Salesforce, Slack, etc.)
+ *
+ * Like biological synapses that transmit signals between neurons, these
+ * connect Brainy to external data sources, enabling seamless information flow.
+ *
+ * They are managed through the Brain Cloud augmentation registry alongside
+ * other augmentations, enabling unified discovery, installation, and updates.
+ *
+ * Example synapses:
+ * - NotionSynapse: Sync pages, databases, and blocks
+ * - SalesforceSynapse: Sync contacts, leads, opportunities
+ * - SlackSynapse: Sync messages, channels, users
+ * - GoogleDriveSynapse: Sync documents, sheets, presentations
+ */
+import { AugmentationResponse } from '../types/augmentations.js';
+import { BaseAugmentation } from './brainyAugmentation.js';
+import { NeuralImportAugmentation } from './neuralImport.js';
+/**
+ * Base class for all synapse augmentations
+ * Provides common functionality for external data synchronization
+ */
+export declare abstract class SynapseAugmentation extends BaseAugmentation {
+    readonly timing: "after";
+    readonly operations: ("all")[];
+    readonly priority = 10;
+    abstract readonly synapseId: string;
+    abstract readonly supportedTypes: string[];
+    protected syncInProgress: boolean;
+    protected lastSyncId?: string;
+    protected syncStats: {
+        totalSyncs: number;
+        totalItems: number;
+        lastSync: string | undefined;
+    };
+    protected neuralImport?: NeuralImportAugmentation;
+    protected useNeuralImport: boolean;
+    protected onInit(): Promise<void>;
+    /**
+     * Synapse-specific initialization
+     * Override this in implementations
+     */
+    protected abstract onInitialize(): Promise<void>;
+    /**
+     * BrainyAugmentation execute method
+     * Intercepts operations to sync external data when relevant
+     */
+    execute<T = any>(operation: string, params: any, next: () => Promise<T>): Promise<T>;
+    /**
+     * Determine if sync should be triggered after an operation
+     */
+    protected shouldSync(operation: string, params: any): boolean;
+    /**
+     * Background sync process
+     */
+    protected backgroundSync(): Promise<void>;
+    protected onShutdown(): Promise<void>;
+    protected onSynapseShutdown(): Promise<void>;
+    /**
+     * ISynapseAugmentation methods
+     */
+    abstract testConnection(): Promise<AugmentationResponse<boolean>>;
+    abstract startSync(options?: Record<string, unknown>): Promise<AugmentationResponse<{
+        synced: number;
+        failed: number;
+        skipped: number;
+        duration: number;
+        errors?: Array<{
+            item: string;
+            error: string;
+        }>;
+    }>>;
+    stopSync(): Promise<void>;
+    abstract incrementalSync(lastSyncId?: string): Promise<AugmentationResponse<{
+        synced: number;
+        failed: number;
+        skipped: number;
+        duration: number;
+        hasMore: boolean;
+        nextSyncId?: string;
+    }>>;
+    abstract previewSync(limit?: number): Promise<AugmentationResponse<{
+        items: Array<{
+            type: string;
+            title: string;
+            preview: string;
+        }>;
+        totalCount: number;
+        estimatedDuration: number;
+    }>>;
+    getSynapseStatus(): Promise<AugmentationResponse<{
+        status: 'connected' | 'disconnected' | 'syncing' | 'error';
+        lastSync?: string;
+        nextSync?: string;
+        totalSyncs: number;
+        totalItems: number;
+    }>>;
+    /**
+     * Helper method to store synced data in Brainy
+     * Optionally uses Neural Import for intelligent processing
+     */
+    protected storeInBrainy(content: string | Record<string, any>, metadata: Record<string, any>, options?: {
+        useNeuralImport?: boolean;
+        dataType?: string;
+        rawData?: Buffer | string;
+    }): Promise<void>;
+    /**
+     * Helper method to query existing synced data
+     */
+    protected queryBrainyData(filter: {
+        connector?: string;
+        [key: string]: any;
+    }): Promise<any[]>;
+}
+/**
+ * Example implementation for reference
+ * Real synapses would be in Brain Cloud registry
+ */
+export declare class ExampleFileSystemSynapse extends SynapseAugmentation {
+    readonly name = "example-filesystem-synapse";
+    readonly description = "Example synapse for local file system with Neural Import intelligence";
+    readonly synapseId = "filesystem";
+    readonly supportedTypes: string[];
+    protected onInitialize(): Promise<void>;
+    testConnection(): Promise<AugmentationResponse<boolean>>;
+    startSync(options?: Record<string, unknown>): Promise<AugmentationResponse<{
+        synced: number;
+        failed: number;
+        skipped: number;
+        duration: number;
+        errors?: Array<{
+            item: string;
+            error: string;
+        }>;
+    }>>;
+    incrementalSync(lastSyncId?: string): Promise<AugmentationResponse<{
+        synced: number;
+        failed: number;
+        skipped: number;
+        duration: number;
+        hasMore: boolean;
+        nextSyncId?: string;
+    }>>;
+    previewSync(limit?: number): Promise<AugmentationResponse<{
+        items: Array<{
+            type: string;
+            title: string;
+            preview: string;
+        }>;
+        totalCount: number;
+        estimatedDuration: number;
+    }>>;
+}