@rool-dev/sdk 0.3.1 → 0.3.2-dev.1f10ef1

package/dist/channel.js

@@ -36,6 +36,7 @@ export class RoolChannel extends EventEmitter {
     _linkAccess;
     _userId;
     _channelId;
+    _conversationId;
     _closed = false;
     graphqlClient;
     mediaClient;
@@ -49,6 +50,7 @@ export class RoolChannel extends EventEmitter {
     _channel;
     _objectIds;
     _objectStats;
+    _hasConnected = false;
     // Object collection: tracks pending local mutations for dedup
     // Maps objectId → optimistic object data (for create/update) or null (for delete)
     _pendingMutations = new Map();
@@ -65,6 +67,7 @@ export class RoolChannel extends EventEmitter {
         this._userId = config.userId;
         this._emitterLogger = config.logger;
         this._channelId = config.channelId;
+        this._conversationId = 'default';
         this.graphqlClient = config.graphqlClient;
         this.mediaClient = config.mediaClient;
         this.logger = config.logger;
@@ -133,17 +136,83 @@ export class RoolChannel extends EventEmitter {
     get channelId() {
         return this._channelId;
     }
+    /**
+     * Get the conversation ID for this channel.
+     * Defaults to 'default' for most apps.
+     */
+    get conversationId() {
+        return this._conversationId;
+    }
     get isReadOnly() {
         return this._role === 'viewer';
     }
+    /**
+     * Get the app URL if this channel was created via installApp, or null.
+     */
+    get appUrl() {
+        return this._channel?.appUrl ?? null;
+    }
     // ===========================================================================
     // Channel History Access
     // ===========================================================================
     /**
-     * Get interactions for this channel.
+     * Get interactions for the current conversation.
      */
     getInteractions() {
-        return this._channel?.interactions ?? [];
+        return this._getInteractionsImpl(this._conversationId);
+    }
+    /** @internal */
+    _getInteractionsImpl(conversationId) {
+        return this._channel?.conversations[conversationId]?.interactions ?? [];
+    }
+    /**
+     * Get all conversations in this channel.
+     * Returns summary info (no full interaction data) for each conversation.
+     */
+    getConversations() {
+        if (!this._channel)
+            return [];
+        return Object.entries(this._channel.conversations).map(([id, conv]) => ({
+            id,
+            name: conv.name ?? null,
+            systemInstruction: conv.systemInstruction ?? null,
+            createdAt: conv.createdAt,
+            createdBy: conv.createdBy,
+            interactionCount: conv.interactions.length,
+        }));
+    }
+    /**
+     * Delete a conversation from this channel.
+     * Cannot delete the conversation you are currently using.
+     */
+    async deleteConversation(conversationId) {
+        if (conversationId === this._conversationId) {
+            throw new Error('Cannot delete the active conversation');
+        }
+        await this.graphqlClient.deleteConversation(this._id, this._channelId, conversationId);
+        // Optimistic local update — remove from cache and emit event
+        // in case the server doesn't send a conversation_updated event for deletes
+        if (this._channel?.conversations[conversationId]) {
+            delete this._channel.conversations[conversationId];
+            this.emit('conversationUpdated', {
+                conversationId,
+                channelId: this._channelId,
+                source: 'local_user',
+            });
+        }
+    }
+    // ===========================================================================
+    // Conversations
+    // ===========================================================================
+    /**
+     * Get a handle for a specific conversation within this channel.
+     * The handle scopes AI and mutation operations to that conversation's
+     * interaction history, while sharing the channel's single SSE connection.
+     *
+     * Conversations are auto-created on first interaction — no explicit create needed.
+     */
+    conversation(conversationId) {
+        return new ConversationHandle(this, conversationId);
     }
     // ===========================================================================
     // Channel Lifecycle
@@ -246,7 +315,11 @@ export class RoolChannel extends EventEmitter {
      * @returns The matching objects and a descriptive message.
      */
     async findObjects(options) {
-        return this.graphqlClient.findObjects(this._id, options, this._channelId);
+        return this._findObjectsImpl(options, this._conversationId);
+    }
+    /** @internal */
+    _findObjectsImpl(options, conversationId) {
+        return this.graphqlClient.findObjects(this._id, options, this._channelId, conversationId);
     }
     /**
      * Get all object IDs (sync, from local cache).
@@ -271,6 +344,10 @@ export class RoolChannel extends EventEmitter {
      * @returns The created object (with AI-filled content) and message
      */
     async createObject(options) {
+        return this._createObjectImpl(options, this._conversationId);
+    }
+    /** @internal */
+    async _createObjectImpl(options, conversationId) {
         const { data, ephemeral } = options;
         // Use data.id if provided (string), otherwise generate
         const objectId = typeof data.id === 'string' ? data.id : generateEntityId();
@@ -285,7 +362,8 @@ export class RoolChannel extends EventEmitter {
         try {
             // Await mutation — server processes AI placeholders before responding.
             // SSE events arrive during the await and are buffered via _deliverObject.
-            const { message } = await this.graphqlClient.createObject(this.id, dataWithId, this._channelId, ephemeral);
+            const interactionId = generateEntityId();
+            const { message } = await this.graphqlClient.createObject(this.id, dataWithId, this._channelId, conversationId, interactionId, ephemeral);
             // Collect resolved object from buffer (or wait if not yet arrived)
             const object = await this._collectObject(objectId);
             return { object, message };
@@ -309,6 +387,10 @@ export class RoolChannel extends EventEmitter {
      * @returns The updated object (with AI-filled content) and message
      */
     async updateObject(objectId, options) {
+        return this._updateObjectImpl(objectId, options, this._conversationId);
+    }
+    /** @internal */
+    async _updateObjectImpl(objectId, options, conversationId) {
         const { data, ephemeral } = options;
         // id is immutable after creation (but null/undefined means delete attempt, which we also reject)
         if (data?.id !== undefined && data.id !== null) {
@@ -334,7 +416,8 @@ export class RoolChannel extends EventEmitter {
             this.emit('objectUpdated', { objectId, object: optimistic, source: 'local_user' });
         }
         try {
-            const { message } = await this.graphqlClient.updateObject(this.id, objectId, this._channelId, serverData, options.prompt, ephemeral);
+            const interactionId = generateEntityId();
+            const { message } = await this.graphqlClient.updateObject(this.id, objectId, this._channelId, conversationId, interactionId, serverData, options.prompt, ephemeral);
             const object = await this._collectObject(objectId);
             return { object, message };
         }
@@ -352,6 +435,10 @@ export class RoolChannel extends EventEmitter {
      * Other objects that reference deleted objects via data fields will retain stale ref values.
      */
     async deleteObjects(objectIds) {
+        return this._deleteObjectsImpl(objectIds, this._conversationId);
+    }
+    /** @internal */
+    async _deleteObjectsImpl(objectIds, conversationId) {
         if (objectIds.length === 0)
             return;
         // Track for dedup and emit optimistic events
@@ -360,7 +447,7 @@ export class RoolChannel extends EventEmitter {
             this.emit('objectDeleted', { objectId, source: 'local_user' });
         }
         try {
-            await this.graphqlClient.deleteObjects(this.id, objectIds, this._channelId);
+            await this.graphqlClient.deleteObjects(this.id, objectIds, this._channelId, conversationId);
         }
         catch (error) {
             this.logger.error('[RoolChannel] Failed to delete objects:', error);
@@ -389,6 +476,10 @@ export class RoolChannel extends EventEmitter {
      * @returns The created CollectionDef
      */
     async createCollection(name, fields) {
+        return this._createCollectionImpl(name, fields, this._conversationId);
+    }
+    /** @internal */
+    async _createCollectionImpl(name, fields, conversationId) {
         if (this._schema[name]) {
             throw new Error(`Collection "${name}" already exists`);
         }
@@ -396,7 +487,7 @@ export class RoolChannel extends EventEmitter {
         const optimisticDef = { fields: fields.map(f => ({ name: f.name, type: f.type })) };
         this._schema[name] = optimisticDef;
         try {
-            return await this.graphqlClient.createCollection(this._id, name, fields, this._channelId);
+            return await this.graphqlClient.createCollection(this._id, name, fields, this._channelId, conversationId);
         }
         catch (error) {
             this.logger.error('[RoolChannel] Failed to create collection:', error);
@@ -411,6 +502,10 @@ export class RoolChannel extends EventEmitter {
      * @returns The updated CollectionDef
      */
     async alterCollection(name, fields) {
+        return this._alterCollectionImpl(name, fields, this._conversationId);
+    }
+    /** @internal */
+    async _alterCollectionImpl(name, fields, conversationId) {
         if (!this._schema[name]) {
             throw new Error(`Collection "${name}" not found`);
         }
@@ -418,7 +513,7 @@ export class RoolChannel extends EventEmitter {
         // Optimistic local update
         this._schema[name] = { fields: fields.map(f => ({ name: f.name, type: f.type })) };
         try {
-            return await this.graphqlClient.alterCollection(this._id, name, fields, this._channelId);
+            return await this.graphqlClient.alterCollection(this._id, name, fields, this._channelId, conversationId);
         }
         catch (error) {
             this.logger.error('[RoolChannel] Failed to alter collection:', error);
@@ -431,6 +526,10 @@ export class RoolChannel extends EventEmitter {
      * @param name - Name of the collection to drop
      */
     async dropCollection(name) {
+        return this._dropCollectionImpl(name, this._conversationId);
+    }
+    /** @internal */
+    async _dropCollectionImpl(name, conversationId) {
         if (!this._schema[name]) {
             throw new Error(`Collection "${name}" not found`);
         }
@@ -438,7 +537,7 @@ export class RoolChannel extends EventEmitter {
         // Optimistic local update
         delete this._schema[name];
         try {
-            await this.graphqlClient.dropCollection(this._id, name, this._channelId);
+            await this.graphqlClient.dropCollection(this._id, name, this._channelId, conversationId);
         }
         catch (error) {
             this.logger.error('[RoolChannel] Failed to drop collection:', error);
@@ -450,48 +549,118 @@ export class RoolChannel extends EventEmitter {
     // System Instructions
     // ===========================================================================
     /**
-     * Get the system instruction for this channel.
+     * Get the system instruction for the current conversation.
      * Returns undefined if no system instruction is set.
      */
     getSystemInstruction() {
-        return this._channel?.systemInstruction;
+        return this._getSystemInstructionImpl(this._conversationId);
+    }
+    /** @internal */
+    _getSystemInstructionImpl(conversationId) {
+        return this._channel?.conversations[conversationId]?.systemInstruction;
     }
     /**
-     * Set the system instruction for this channel.
+     * Set the system instruction for the current conversation.
      * Pass null to clear the instruction.
      */
     async setSystemInstruction(instruction) {
+        return this._setSystemInstructionImpl(instruction, this._conversationId);
+    }
+    /** @internal */
+    async _setSystemInstructionImpl(instruction, conversationId) {
         // Optimistic local update
-        if (!this._channel) {
-            this._channel = {
-                createdAt: Date.now(),
-                createdBy: this._userId,
-                interactions: [],
-            };
-        }
-        const previous = this._channel;
+        this._ensureConversationImpl(conversationId);
+        const conv = this._channel.conversations[conversationId];
+        const previousInstruction = conv.systemInstruction;
         if (instruction === null) {
-            const { systemInstruction: _, ...rest } = this._channel;
-            this._channel = rest;
+            delete conv.systemInstruction;
         }
         else {
-            this._channel = { ...this._channel, systemInstruction: instruction };
+            conv.systemInstruction = instruction;
         }
-        // Emit event
-        this.emit('channelUpdated', {
+        // Emit events for backward compat and new API
+        this.emit('conversationUpdated', {
+            conversationId,
             channelId: this._channelId,
             source: 'local_user',
         });
+        if (conversationId === this._conversationId) {
+            this.emit('channelUpdated', {
+                channelId: this._channelId,
+                source: 'local_user',
+            });
+        }
         // Call server
         try {
-            await this.graphqlClient.setSystemInstruction(this.id, this._channelId, instruction);
+            await this.graphqlClient.updateConversation(this._id, this._channelId, conversationId, { systemInstruction: instruction });
         }
         catch (error) {
             this.logger.error('[RoolChannel] Failed to set system instruction:', error);
-            this._channel = previous;
+            // Rollback
+            if (previousInstruction === undefined) {
+                delete conv.systemInstruction;
+            }
+            else {
+                conv.systemInstruction = previousInstruction;
+            }
+            throw error;
+        }
+    }
+    /**
+     * Rename the current conversation.
+     */
+    async renameConversation(name) {
+        return this._renameConversationImpl(name, this._conversationId);
+    }
+    /** @internal */
+    async _renameConversationImpl(name, conversationId) {
+        // Optimistic local update
+        this._ensureConversationImpl(conversationId);
+        const conv = this._channel.conversations[conversationId];
+        const previousName = conv.name;
+        conv.name = name;
+        this.emit('conversationUpdated', {
+            conversationId,
+            channelId: this._channelId,
+            source: 'local_user',
+        });
+        if (conversationId === this._conversationId) {
+            this.emit('channelUpdated', {
+                channelId: this._channelId,
+                source: 'local_user',
+            });
+        }
+        // Call server
+        try {
+            await this.graphqlClient.updateConversation(this._id, this._channelId, conversationId, { name });
+        }
+        catch (error) {
+            this.logger.error('[RoolChannel] Failed to rename conversation:', error);
+            // Rollback
+            conv.name = previousName;
             throw error;
         }
     }
+    /**
+     * Ensure a conversation exists in the local channel cache.
+     * @internal
+     */
+    _ensureConversationImpl(conversationId) {
+        if (!this._channel) {
+            this._channel = {
+                createdAt: Date.now(),
+                createdBy: this._userId,
+                conversations: {},
+            };
+        }
+        if (!this._channel.conversations[conversationId]) {
+            this._channel.conversations[conversationId] = {
+                createdAt: Date.now(),
+                createdBy: this._userId,
+                interactions: [],
+            };
+        }
+    }
     // ===========================================================================
     // Metadata Operations
     // ===========================================================================
@@ -500,10 +669,14 @@ export class RoolChannel extends EventEmitter {
      * Metadata is stored in meta and hidden from AI operations.
      */
     setMetadata(key, value) {
+        this._setMetadataImpl(key, value, this._conversationId);
+    }
+    /** @internal */
+    _setMetadataImpl(key, value, conversationId) {
         this._meta[key] = value;
         this.emit('metadataUpdated', { metadata: this._meta, source: 'local_user' });
         // Fire-and-forget server call
-        this.graphqlClient.setSpaceMeta(this.id, this._meta, this._channelId)
+        this.graphqlClient.setSpaceMeta(this.id, this._meta, this._channelId, conversationId)
             .catch((error) => {
             this.logger.error('[RoolChannel] Failed to set meta:', error);
         });
@@ -528,13 +701,18 @@ export class RoolChannel extends EventEmitter {
      * @returns The message from the AI and the list of objects that were created or modified
      */
     async prompt(prompt, options) {
+        return this._promptImpl(prompt, options, this._conversationId);
+    }
+    /** @internal */
+    async _promptImpl(prompt, options, conversationId) {
         // Upload attachments via media endpoint, then send URLs to the server
         const { attachments, ...rest } = options ?? {};
         let attachmentUrls;
         if (attachments?.length) {
             attachmentUrls = await Promise.all(attachments.map(file => this.mediaClient.upload(this._id, file)));
         }
-        const result = await this.graphqlClient.prompt(this._id, prompt, this._channelId, { ...rest, attachmentUrls });
+        const interactionId = generateEntityId();
+        const result = await this.graphqlClient.prompt(this._id, prompt, this._channelId, conversationId, { ...rest, attachmentUrls, interactionId });
         // Collect modified objects — they arrive via SSE events during/after the mutation.
         // Try collecting from buffer first, then fetch any missing from server.
         const objects = [];
@@ -569,7 +747,24 @@ export class RoolChannel extends EventEmitter {
      * Rename this channel.
      */
     async rename(newName) {
-        await this.graphqlClient.renameChannel(this._id, this._channelId, newName);
+        // Optimistic local update
+        const previousName = this._channel?.name;
+        if (this._channel) {
+            this._channel.name = newName;
+        }
+        this.emit('channelUpdated', { channelId: this._channelId, source: 'local_user' });
+        // Call server
+        try {
+            await this.graphqlClient.renameChannel(this._id, this._channelId, newName);
+        }
+        catch (error) {
+            this.logger.error('[RoolChannel] Failed to rename channel:', error);
+            // Rollback
+            if (this._channel) {
+                this._channel.name = previousName;
+            }
+            throw error;
+        }
     }
     // ===========================================================================
     // Media Operations
@@ -671,6 +866,23 @@ export class RoolChannel extends EventEmitter {
             return;
         const changeSource = event.source === 'agent' ? 'remote_agent' : 'remote_user';
         switch (event.type) {
+            case 'connected':
+                // On reconnection, do a full reload to catch up on missed events.
+                // Skip on initial connection — data was already fetched by openChannel.
+                if (this._hasConnected) {
+                    void this.graphqlClient.openChannel(this._id, this._channelId).then((result) => {
+                        if (this._closed)
+                            return;
+                        this._meta = result.meta;
+                        this._schema = result.schema;
+                        this._channel = result.channel;
+                        this._objectIds = result.objectIds;
+                        this._objectStats = new Map(Object.entries(result.objectStats));
+                        this.emit('reset', { source: 'system' });
+                    });
+                }
+                this._hasConnected = true;
+                break;
             case 'object_created':
                 if (event.objectId && event.object) {
                     if (event.objectStat)
@@ -694,6 +906,7 @@ export class RoolChannel extends EventEmitter {
             case 'schema_updated':
                 if (event.schema) {
                     this._schema = event.schema;
+                    this.emit('schemaUpdated', { schema: this._schema, source: changeSource });
                 }
                 break;
             case 'metadata_updated':
@@ -703,10 +916,47 @@ export class RoolChannel extends EventEmitter {
                 }
                 break;
             case 'channel_updated':
-                // Only update if it's our channel
+                // Only update if it's our channel — channel_updated is now metadata-only (name, appUrl)
                 if (event.channelId === this._channelId && event.channel) {
+                    const changed = JSON.stringify(this._channel) !== JSON.stringify(event.channel);
                     this._channel = event.channel;
-                    this.emit('channelUpdated', { channelId: event.channelId, source: changeSource });
+                    if (changed) {
+                        this.emit('channelUpdated', { channelId: event.channelId, source: changeSource });
+                    }
+                }
+                break;
+            case 'conversation_updated':
+                // Only update if it's our channel
+                if (event.channelId === this._channelId && event.conversationId) {
+                    if (!this._channel) {
+                        this._channel = {
+                            createdAt: Date.now(),
+                            createdBy: this._userId,
+                            conversations: {},
+                        };
+                    }
+                    const prev = this._channel.conversations[event.conversationId];
+                    if (event.conversation) {
+                        // Update or create conversation in local cache
+                        this._channel.conversations[event.conversationId] = event.conversation;
+                    }
+                    else {
+                        // Conversation was deleted
+                        delete this._channel.conversations[event.conversationId];
+                    }
+                    // Skip emit if data is unchanged (e.g. echo of our own optimistic update)
+                    if (JSON.stringify(prev) === JSON.stringify(event.conversation))
+                        break;
+                    // Emit the new conversationUpdated event
+                    this.emit('conversationUpdated', {
+                        conversationId: event.conversationId,
+                        channelId: event.channelId,
+                        source: changeSource,
+                    });
+                    // Backward compat: also emit channelUpdated when the active conversation updates
+                    if (event.conversationId === this._conversationId) {
+                        this.emit('channelUpdated', { channelId: event.channelId, source: changeSource });
+                    }
                 }
                 break;
             case 'space_changed':
@@ -797,4 +1047,95 @@ export class RoolChannel extends EventEmitter {
         }
     }
 }
+// =============================================================================
+// ConversationHandle — Scoped proxy for a specific conversation
+// =============================================================================
+/**
+ * A lightweight handle for a specific conversation within a channel.
+ *
+ * Scopes AI and mutation operations to a particular conversation's interaction
+ * history, while sharing the channel's single SSE connection and object state.
+ *
+ * Obtain via `channel.conversation('thread-id')`.
+ * Conversations are auto-created on first interaction.
+ */
+export class ConversationHandle {
+    /** @internal */
+    _channel;
+    _conversationId;
+    /** @internal */
+    constructor(channel, conversationId) {
+        this._channel = channel;
+        this._conversationId = conversationId;
+    }
+    /** The conversation ID this handle is scoped to. */
+    get conversationId() { return this._conversationId; }
+    // ---------------------------------------------------------------------------
+    // Conversation History
+    // ---------------------------------------------------------------------------
+    /** Get interactions for this conversation. */
+    getInteractions() {
+        return this._channel._getInteractionsImpl(this._conversationId);
+    }
+    /** Get the system instruction for this conversation. */
+    getSystemInstruction() {
+        return this._channel._getSystemInstructionImpl(this._conversationId);
+    }
+    /** Set the system instruction for this conversation. Pass null to clear. */
+    async setSystemInstruction(instruction) {
+        return this._channel._setSystemInstructionImpl(instruction, this._conversationId);
+    }
+    /** Rename this conversation. */
+    async rename(name) {
+        return this._channel._renameConversationImpl(name, this._conversationId);
+    }
+    // ---------------------------------------------------------------------------
+    // Object Operations (scoped to this conversation's interaction history)
+    // ---------------------------------------------------------------------------
+    /** Find objects using structured filters and/or natural language. */
+    async findObjects(options) {
+        return this._channel._findObjectsImpl(options, this._conversationId);
+    }
+    /** Create a new object. */
+    async createObject(options) {
+        return this._channel._createObjectImpl(options, this._conversationId);
+    }
+    /** Update an existing object. */
+    async updateObject(objectId, options) {
+        return this._channel._updateObjectImpl(objectId, options, this._conversationId);
+    }
+    /** Delete objects by IDs. */
+    async deleteObjects(objectIds) {
+        return this._channel._deleteObjectsImpl(objectIds, this._conversationId);
+    }
+    // ---------------------------------------------------------------------------
+    // AI
+    // ---------------------------------------------------------------------------
+    /** Send a prompt to the AI agent, scoped to this conversation's history. */
+    async prompt(text, options) {
+        return this._channel._promptImpl(text, options, this._conversationId);
+    }
+    // ---------------------------------------------------------------------------
+    // Schema (scoped to this conversation's interaction history)
+    // ---------------------------------------------------------------------------
+    /** Create a new collection schema. */
+    async createCollection(name, fields) {
+        return this._channel._createCollectionImpl(name, fields, this._conversationId);
+    }
+    /** Alter an existing collection schema. */
+    async alterCollection(name, fields) {
+        return this._channel._alterCollectionImpl(name, fields, this._conversationId);
+    }
+    /** Drop a collection schema. */
+    async dropCollection(name) {
+        return this._channel._dropCollectionImpl(name, this._conversationId);
+    }
+    // ---------------------------------------------------------------------------
+    // Metadata (scoped to this conversation's interaction history)
+    // ---------------------------------------------------------------------------
+    /** Set a space-level metadata value. */
+    setMetadata(key, value) {
+        return this._channel._setMetadataImpl(key, value, this._conversationId);
+    }
+}
 //# sourceMappingURL=channel.js.map