@rool-dev/client 0.3.1 → 0.4.0-dev.22f8ef0

package/dist/space.js

@@ -0,0 +1,730 @@
+import { immutableJSONPatch } from 'immutable-json-patch';
+import { EventEmitter } from './event-emitter.js';
+const MAX_UNDO_STACK_SIZE = 50;
+// 6-character alphanumeric ID (62^6 = 56.8 billion possible values)
+const ID_CHARS = '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz';
+export function generateEntityId() {
+    let result = '';
+    for (let i = 0; i < 6; i++) {
+        result += ID_CHARS[Math.floor(Math.random() * ID_CHARS.length)];
+    }
+    return result;
+}
+/**
+ * First-class Space object.
+ *
+ * Features:
+ * - High-level object/link operations
+ * - Built-in undo/redo with checkpoints
+ * - Metadata management
+ * - Event emission for state changes
+ * - Real-time subscription support
+ */
+export class RoolSpace extends EventEmitter {
+    _id;
+    _name;
+    _role;
+    _data;
+    graphqlClient;
+    mediaClient;
+    onRegisterForEvents;
+    onUnregisterFromEvents;
+    // Undo/redo stacks
+    undoStack = [];
+    redoStack = [];
+    // Subscription state
+    _isSubscribed = false;
+    constructor(config) {
+        super();
+        this._id = config.id;
+        this._name = config.name;
+        this._role = config.role;
+        this._data = config.initialData;
+        this.graphqlClient = config.graphqlClient;
+        this.mediaClient = config.mediaClient;
+        this.onRegisterForEvents = config.onRegisterForEvents;
+        this.onUnregisterFromEvents = config.onUnregisterFromEvents;
+    }
+    // ===========================================================================
+    // Properties
+    // ===========================================================================
+    get id() {
+        return this._id;
+    }
+    get name() {
+        return this._name;
+    }
+    get role() {
+        return this._role;
+    }
+    get isReadOnly() {
+        return this._role === 'viewer';
+    }
+    get isSubscribed() {
+        return this._isSubscribed;
+    }
+    // ===========================================================================
+    // Space Lifecycle
+    // ===========================================================================
+    /**
+     * Rename this space.
+     */
+    async rename(newName) {
+        const oldName = this._name;
+        this._name = newName;
+        try {
+            await this.graphqlClient.renameSpace(this._id, newName);
+        }
+        catch (error) {
+            this._name = oldName;
+            throw error;
+        }
+    }
+    /**
+     * Subscribe to real-time updates for this space.
+     * Registers with the client for event routing.
+     */
+    subscribe() {
+        if (this._isSubscribed)
+            return;
+        this._isSubscribed = true;
+        this.onRegisterForEvents(this._id, this);
+    }
+    /**
+     * Unsubscribe from real-time updates.
+     */
+    unsubscribe() {
+        if (!this._isSubscribed)
+            return;
+        this._isSubscribed = false;
+        this.onUnregisterFromEvents(this._id);
+    }
+    /**
+     * Close this space and clean up resources.
+     */
+    close() {
+        this.unsubscribe();
+        this.undoStack = [];
+        this.redoStack = [];
+        this.removeAllListeners();
+    }
+    // ===========================================================================
+    // Undo / Redo
+    // ===========================================================================
+    /**
+     * Create a checkpoint for undo.
+     * Call this before a user action to capture the current state.
+     */
+    checkpoint(label = 'Change') {
+        const entry = {
+            timestamp: Date.now(),
+            label,
+            data: JSON.parse(JSON.stringify(this._data)),
+        };
+        this.undoStack.push(entry);
+        // Limit stack size
+        if (this.undoStack.length > MAX_UNDO_STACK_SIZE) {
+            this.undoStack.shift();
+        }
+        // Clear redo stack (new action invalidates redo)
+        this.redoStack = [];
+    }
+    /**
+     * Check if undo is available.
+     */
+    canUndo() {
+        return this.undoStack.length > 0;
+    }
+    /**
+     * Check if redo is available.
+     */
+    canRedo() {
+        return this.redoStack.length > 0;
+    }
+    /**
+     * Undo to the previous checkpoint.
+     * @returns true if undo was performed
+     */
+    async undo() {
+        if (!this.canUndo())
+            return false;
+        // Save current state to redo stack
+        const currentEntry = {
+            timestamp: Date.now(),
+            label: 'Redo point',
+            data: JSON.parse(JSON.stringify(this._data)),
+        };
+        this.redoStack.push(currentEntry);
+        // Restore previous state
+        const previousEntry = this.undoStack.pop();
+        this._data = previousEntry.data;
+        // Sync to server - resync on failure
+        try {
+            await this.graphqlClient.setSpace(this._id, this._data);
+            this.emit('reset', { source: 'local_user' });
+        }
+        catch (error) {
+            console.error('[Space] Failed to sync undo to server:', error);
+            await this.resyncFromServer(error instanceof Error ? error : new Error(String(error)));
+        }
+        return true;
+    }
+    /**
+     * Redo a previously undone action.
+     * @returns true if redo was performed
+     */
+    async redo() {
+        if (!this.canRedo())
+            return false;
+        // Save current state to undo stack
+        const currentEntry = {
+            timestamp: Date.now(),
+            label: 'Undo point',
+            data: JSON.parse(JSON.stringify(this._data)),
+        };
+        this.undoStack.push(currentEntry);
+        // Restore next state
+        const nextEntry = this.redoStack.pop();
+        this._data = nextEntry.data;
+        // Sync to server - resync on failure
+        try {
+            await this.graphqlClient.setSpace(this._id, this._data);
+            this.emit('reset', { source: 'local_user' });
+        }
+        catch (error) {
+            console.error('[Space] Failed to sync redo to server:', error);
+            await this.resyncFromServer(error instanceof Error ? error : new Error(String(error)));
+        }
+        return true;
+    }
+    /**
+     * Clear undo/redo history.
+     * Called when external changes invalidate local history.
+     */
+    clearHistory() {
+        this.undoStack = [];
+        this.redoStack = [];
+    }
+    // ===========================================================================
+    // Object Operations
+    // ===========================================================================
+    /**
+     * Get an object's data by ID.
+     * Returns just the data portion (RoolObject), not the full entry with meta/links.
+     * @throws Error if object not found
+     */
+    getObject(objectId) {
+        const entry = this._data.objects[objectId];
+        if (!entry) {
+            throw new Error(`Object ${objectId} not found`);
+        }
+        return entry.data;
+    }
+    /**
+     * Get an object's data by ID, or undefined if not found.
+     */
+    getObjectOrUndefined(objectId) {
+        return this._data.objects[objectId]?.data;
+    }
+    /**
+     * Get an object's metadata (position, UI state, etc).
+     */
+    getObjectMeta(objectId) {
+        const entry = this._data.objects[objectId];
+        if (!entry) {
+            throw new Error(`Object ${objectId} not found`);
+        }
+        return entry.meta;
+    }
+    /**
+     * Query objects by field values.
+     * Returns all objects where all specified fields match the given values.
+     *
+     * @example
+     * space.queryObjects({ type: 'article' })
+     * space.queryObjects({ type: 'task', status: 'done' })
+     */
+    queryObjects(where) {
+        return Object.values(this._data.objects)
+            .filter(entry => {
+            return Object.entries(where).every(([key, value]) => entry.data[key] === value);
+        })
+            .map(entry => entry.data);
+    }
+    /**
+     * Get all object IDs.
+     */
+    getObjectIds() {
+        return Object.keys(this._data.objects);
+    }
+    /**
+     * Create a new object with optional AI generation.
+     * @param options.data - Object data fields (any key-value pairs). Use {{placeholder}} for AI-generated content.
+     * @param options.meta - Client-private metadata (optional). Hidden from AI operations.
+     * @param options.prompt - AI prompt for content generation (optional).
+     * @returns The generated object ID
+     */
+    async createObject(options) {
+        const objectId = generateEntityId();
+        const { data, meta, prompt } = options;
+        // Build the entry for local state
+        const entry = {
+            meta: meta ?? {},
+            links: {},
+            data,
+        };
+        // Update local state immediately (optimistic)
+        this._data.objects[objectId] = entry;
+        this.emit('objectCreated', { objectId, object: entry.data, source: 'local_user' });
+        // Await server call
+        try {
+            const message = await this.graphqlClient.createObject(this.id, objectId, data, meta, prompt);
+            return { id: objectId, message };
+        }
+        catch (error) {
+            console.error('[Space] Failed to create object:', error);
+            this.resyncFromServer(error instanceof Error ? error : new Error(String(error)));
+            throw error;
+        }
+    }
+    /**
+     * Update an existing object.
+     * @param objectId - The ID of the object to update
+     * @param options.data - Fields to add or update. Use {{placeholder}} for AI-generated content.
+     * @param options.meta - Client-private metadata to merge. Hidden from AI operations.
+     * @param options.prompt - AI prompt for content editing (optional).
+     */
+    async updateObject(objectId, options) {
+        const entry = this._data.objects[objectId];
+        if (!entry) {
+            throw new Error(`Object ${objectId} not found for update`);
+        }
+        const { data, meta } = options;
+        // Build local updates
+        if (data) {
+            Object.assign(entry.data, data);
+        }
+        if (meta) {
+            entry.meta = { ...entry.meta, ...meta };
+        }
+        // Emit semantic event with updated object
+        if (data || meta) {
+            this.emit('objectUpdated', { objectId, object: entry.data, source: 'local_user' });
+        }
+        // Await server call
+        try {
+            return await this.graphqlClient.updateObject(this.id, objectId, data, meta, options.prompt);
+        }
+        catch (error) {
+            console.error('[Space] Failed to update object:', error);
+            this.resyncFromServer(error instanceof Error ? error : new Error(String(error)));
+            throw error;
+        }
+    }
+    /**
+     * Delete objects by IDs.
+     * Outbound links are automatically deleted with the object.
+     * Inbound links become orphans (tolerated).
+     */
+    async deleteObjects(objectIds) {
+        if (objectIds.length === 0)
+            return;
+        const deletedObjectIds = [];
+        // Collect links that will be orphaned (for events)
+        const deletedLinks = [];
+        for (const objectId of objectIds) {
+            const entry = this._data.objects[objectId];
+            if (entry) {
+                // Collect outbound links for deletion events
+                for (const [linkType, targets] of Object.entries(entry.links)) {
+                    for (const targetId of Object.keys(targets)) {
+                        deletedLinks.push({ sourceId: objectId, targetId, linkType });
+                    }
+                }
+            }
+        }
+        // Remove objects (local state)
+        for (const objectId of objectIds) {
+            if (this._data.objects[objectId]) {
+                delete this._data.objects[objectId];
+                deletedObjectIds.push(objectId);
+            }
+        }
+        // Emit semantic events
+        for (const link of deletedLinks) {
+            this.emit('unlinked', { ...link, source: 'local_user' });
+        }
+        for (const objectId of deletedObjectIds) {
+            this.emit('objectDeleted', { objectId, source: 'local_user' });
+        }
+        // Await server call
+        try {
+            await this.graphqlClient.deleteObjects(this.id, objectIds);
+        }
+        catch (error) {
+            console.error('[Space] Failed to delete objects:', error);
+            this.resyncFromServer(error instanceof Error ? error : new Error(String(error)));
+            throw error;
+        }
+    }
+    // ===========================================================================
+    // Link Operations
+    // ===========================================================================
+    /**
+     * Create a link between objects.
+     * Links are stored on the source object.
+     */
+    async link(sourceId, targetId, linkType) {
+        const entry = this._data.objects[sourceId];
+        if (!entry) {
+            throw new Error(`Source object ${sourceId} not found`);
+        }
+        // Update local state immediately
+        if (!entry.links[linkType]) {
+            entry.links[linkType] = {};
+        }
+        entry.links[linkType][targetId] = {};
+        const linkData = entry.links[linkType][targetId];
+        this.emit('linked', { sourceId, targetId, linkType, linkData, source: 'local_user' });
+        // Await server call
+        try {
+            await this.graphqlClient.link(this.id, sourceId, targetId, linkType);
+        }
+        catch (error) {
+            console.error('[Space] Failed to create link:', error);
+            this.resyncFromServer(error instanceof Error ? error : new Error(String(error)));
+            throw error;
+        }
+    }
+    /**
+     * Remove a link between two objects.
+     * @param linkType - Optional: if provided, only removes that type; otherwise removes all links between the objects
+     * @returns true if any links were removed
+     */
+    async unlink(sourceId, targetId, linkType) {
+        const entry = this._data.objects[sourceId];
+        if (!entry) {
+            throw new Error(`Source object ${sourceId} not found`);
+        }
+        const deletedLinks = [];
+        // Update local state
+        if (linkType) {
+            // Remove specific link type
+            if (entry.links[linkType]?.[targetId] !== undefined) {
+                delete entry.links[linkType][targetId];
+                deletedLinks.push({ linkType });
+            }
+        }
+        else {
+            // Remove all links from source to target
+            for (const [type, targets] of Object.entries(entry.links)) {
+                if (targets[targetId] !== undefined) {
+                    delete targets[targetId];
+                    deletedLinks.push({ linkType: type });
+                }
+            }
+        }
+        // Emit semantic events
+        for (const link of deletedLinks) {
+            this.emit('unlinked', { sourceId, targetId, linkType: link.linkType, source: 'local_user' });
+        }
+        // Await server call
+        try {
+            await this.graphqlClient.unlink(this.id, sourceId, targetId);
+        }
+        catch (error) {
+            console.error('[Space] Failed to remove link:', error);
+            this.resyncFromServer(error instanceof Error ? error : new Error(String(error)));
+            throw error;
+        }
+        return deletedLinks.length > 0;
+    }
+    /**
+     * Get parent object IDs (objects that have links pointing TO this object).
+     * @param linkType - Optional filter by link type
+     */
+    getParents(objectId, linkType) {
+        const parents = [];
+        for (const [entryId, entry] of Object.entries(this._data.objects)) {
+            for (const [type, targets] of Object.entries(entry.links)) {
+                if ((!linkType || type === linkType) && objectId in targets) {
+                    parents.push(entryId);
+                    break; // Found a link, move to next object
+                }
+            }
+        }
+        return parents;
+    }
+    /**
+     * Get child object IDs (objects that this object has links pointing TO).
+     * Filters out orphan targets (targets that don't exist).
+     * @param linkType - Optional filter by link type
+     */
+    getChildren(objectId, linkType) {
+        const entry = this._data.objects[objectId];
+        if (!entry)
+            return [];
+        const children = [];
+        for (const [type, targets] of Object.entries(entry.links)) {
+            if (!linkType || type === linkType) {
+                for (const targetId of Object.keys(targets)) {
+                    // Filter orphans - only return existing targets
+                    if (this._data.objects[targetId]) {
+                        children.push(targetId);
+                    }
+                }
+            }
+        }
+        return children;
+    }
+    /**
+     * Get all child object IDs including orphans (targets that may not exist).
+     * @param linkType - Optional filter by link type
+     */
+    getChildrenIncludingOrphans(objectId, linkType) {
+        const entry = this._data.objects[objectId];
+        if (!entry)
+            return [];
+        const children = [];
+        for (const [type, targets] of Object.entries(entry.links)) {
+            if (!linkType || type === linkType) {
+                children.push(...Object.keys(targets));
+            }
+        }
+        return children;
+    }
+    // ===========================================================================
+    // Metadata Operations
+    // ===========================================================================
+    /**
+     * Set a space-level metadata value.
+     * Metadata is stored in meta and hidden from AI operations.
+     */
+    setMetadata(key, value) {
+        if (!this._data.meta) {
+            this._data.meta = {};
+        }
+        this._data.meta[key] = value;
+        this.emit('metaUpdated', { meta: this._data.meta, source: 'local_user' });
+        // Fire-and-forget server call - errors trigger resync
+        this.graphqlClient.setSpaceMeta(this.id, this._data.meta)
+            .catch((error) => {
+            console.error('[Space] Failed to set graph meta:', error);
+            this.resyncFromServer(error instanceof Error ? error : new Error(String(error)));
+        });
+    }
+    /**
+     * Get a space-level metadata value.
+     */
+    getMetadata(key) {
+        return this._data.meta?.[key];
+    }
+    /**
+     * Get all space-level metadata.
+     */
+    getAllMetadata() {
+        return this._data.meta ?? {};
+    }
+    // ===========================================================================
+    // AI Operations
+    // ===========================================================================
+    /**
+     * Send a prompt to the AI agent for space manipulation.
+     */
+    async prompt(prompt, options) {
+        return this.graphqlClient.prompt(this._id, prompt, options);
+    }
+    // ===========================================================================
+    // Collaboration
+    // ===========================================================================
+    /**
+     * List users with access to this space.
+     */
+    async listUsers() {
+        return this.graphqlClient.listSpaceUsers(this._id);
+    }
+    /**
+     * Add a user to this space with specified role.
+     */
+    async addUser(userId, role) {
+        return this.graphqlClient.addSpaceUser(this._id, userId, role);
+    }
+    /**
+     * Remove a user from this space.
+     */
+    async removeUser(userId) {
+        return this.graphqlClient.removeSpaceUser(this._id, userId);
+    }
+    // ===========================================================================
+    // Media Operations
+    // ===========================================================================
+    /**
+     * List all media files for this space.
+     */
+    async listMedia() {
+        return this.mediaClient.list(this._id);
+    }
+    /**
+     * Upload a file to this space.
+     */
+    async uploadMedia(file) {
+        return this.mediaClient.upload(this._id, file);
+    }
+    /**
+     * Get the URL for a media file.
+     */
+    getMediaUrl(uuid) {
+        return this.mediaClient.getUrl(this._id, uuid);
+    }
+    /**
+     * Download a media file as a Blob.
+     */
+    async downloadMedia(uuid) {
+        return this.mediaClient.download(this._id, uuid);
+    }
+    /**
+     * Delete a media file.
+     */
+    async deleteMedia(uuid) {
+        return this.mediaClient.delete(this._id, uuid);
+    }
+    // ===========================================================================
+    // Low-level Operations
+    // ===========================================================================
+    /**
+     * Get the full space data.
+     * Use sparingly - prefer specific operations.
+     */
+    getData() {
+        return this._data;
+    }
+    // ===========================================================================
+    // Event Handlers (called by RoolClient for routing)
+    // ===========================================================================
+    /**
+     * Handle a patch event from another client.
+     * @internal
+     */
+    handleRemotePatch(patch, source = 'user') {
+        try {
+            this._data = immutableJSONPatch(this._data, patch);
+        }
+        catch (error) {
+            console.error('[Space] Failed to apply remote patch:', error);
+            // Force resync on patch error
+            this.resyncFromServer(error instanceof Error ? error : new Error(String(error))).catch(() => { });
+            return;
+        }
+        // Parse patch operations and emit semantic events
+        const changeSource = source === 'agent' ? 'remote_agent' : 'remote_user';
+        this.emitSemanticEventsFromPatch(patch, changeSource);
+    }
+    /**
+     * Parse JSON patch operations and emit semantic events.
+     * @internal
+     */
+    emitSemanticEventsFromPatch(patch, source) {
+        // Track which objects have been updated (to avoid duplicate events)
+        const updatedObjects = new Set();
+        for (const op of patch) {
+            const { path } = op;
+            // Object operations: /objects/{objectId}/...
+            if (path.startsWith('/objects/')) {
+                const parts = path.split('/');
+                const objectId = parts[2];
+                if (parts.length === 3) {
+                    // /objects/{objectId} - full object add or remove
+                    if (op.op === 'add') {
+                        const entry = this._data.objects[objectId];
+                        if (entry) {
+                            this.emit('objectCreated', { objectId, object: entry.data, source });
+                        }
+                    }
+                    else if (op.op === 'remove') {
+                        this.emit('objectDeleted', { objectId, source });
+                    }
+                }
+                else if (parts[3] === 'data') {
+                    // /objects/{objectId}/data/... - data field update
+                    if (!updatedObjects.has(objectId)) {
+                        const entry = this._data.objects[objectId];
+                        if (entry) {
+                            this.emit('objectUpdated', { objectId, object: entry.data, source });
+                            updatedObjects.add(objectId);
+                        }
+                    }
+                }
+                else if (parts[3] === 'links') {
+                    // /objects/{objectId}/links/{type}/{targetId}
+                    if (parts.length >= 6) {
+                        const linkType = parts[4];
+                        const targetId = parts[5];
+                        if (op.op === 'add') {
+                            const linkData = this._data.objects[objectId]?.links[linkType]?.[targetId] ?? {};
+                            this.emit('linked', { sourceId: objectId, targetId, linkType, linkData, source });
+                        }
+                        else if (op.op === 'remove') {
+                            this.emit('unlinked', { sourceId: objectId, targetId, linkType, source });
+                        }
+                    }
+                    else if (parts.length === 5 && op.op === 'add') {
+                        // /objects/{objectId}/links/{type} - new link type object added
+                        const linkType = parts[4];
+                        const targets = this._data.objects[objectId]?.links[linkType] ?? {};
+                        for (const [targetId, linkData] of Object.entries(targets)) {
+                            this.emit('linked', { sourceId: objectId, targetId, linkType, linkData: linkData, source });
+                        }
+                    }
+                }
+                else if (parts[3] === 'meta') {
+                    // /objects/{objectId}/meta/... - object meta update
+                    // Could emit an objectMeta event if needed, but for now treat as object update
+                    if (!updatedObjects.has(objectId)) {
+                        const entry = this._data.objects[objectId];
+                        if (entry) {
+                            this.emit('objectUpdated', { objectId, object: entry.data, source });
+                            updatedObjects.add(objectId);
+                        }
+                    }
+                }
+            }
+            else if (path === '/meta' || path.startsWith('/meta/')) {
+                this.emit('metaUpdated', { meta: this._data.meta, source });
+            }
+        }
+    }
+    /**
+     * Handle a full reload from server.
+     * @internal
+     */
+    handleRemoteChange(newData) {
+        this._data = newData;
+        this.emit('reset', { source: 'remote_user' });
+    }
+    /**
+     * Update the name from external source.
+     * @internal
+     */
+    handleRemoteRename(newName) {
+        this._name = newName;
+    }
+    // ===========================================================================
+    // Private Methods
+    // ===========================================================================
+    async resyncFromServer(originalError) {
+        console.warn('[Space] Resyncing from server after sync failure');
+        try {
+            const serverData = await this.graphqlClient.getSpace(this._id);
+            this._data = serverData;
+            this.clearHistory();
+            this.emit('syncError', originalError ?? new Error('Sync failed'));
+            this.emit('reset', { source: 'system' });
+        }
+        catch (error) {
+            console.error('[Space] Failed to resync from server:', error);
+            // Still emit syncError with the original error
+            this.emit('syncError', originalError ?? new Error('Sync failed'));
+        }
+    }
+}
+//# sourceMappingURL=space.js.map