@rool-dev/svelte 0.2.0 → 0.3.0

package/README.md

@@ -19,7 +19,7 @@ npm install @rool-dev/svelte
   const rool = createRool();
   rool.init();
 
-  let currentSpace = $state(null);
+  let channel = $state(null);
 </script>
 
 {#if !rool.authenticated}
@@ -27,13 +27,13 @@ npm install @rool-dev/svelte
 {:else}
   <h1>My Spaces</h1>
   {#each rool.spaces ?? [] as space}
-    <button onclick={async () => currentSpace = await rool.openSpace(space.id)}>
+    <button onclick={async () => channel = await rool.openChannel(space.id, 'main')}>
       {space.name}
     </button>
   {/each}
 
-  {#if currentSpace}
-    <p>Interactions: {currentSpace.interactions.length}</p>
+  {#if channel}
+    <p>Interactions: {channel.interactions.length}</p>
   {/if}
 {/if}
 ```
@@ -50,9 +50,9 @@ The Svelte wrapper adds reactive state on top of the SDK:
 | `rool.spacesError` | Error from loading spaces |
 | `rool.connectionState` | SSE connection state |
 | `rool.userStorage` | User storage (cross-device preferences) |
-| `space.interactions` | Conversation interactions (auto-updates) |
-| `collection.objects` | Objects matching a filter (auto-updates) |
-| `collection.loading` | Whether collection is loading |
+| `channel.interactions` | Channel interactions (auto-updates) |
+| `watch.objects` | Objects matching a filter (auto-updates) |
+| `watch.loading` | Whether watch is loading |
 
 Everything else passes through to the SDK directly. See the [SDK documentation](../sdk/README.md) for full API details.
 
@@ -65,7 +65,7 @@ const rool = createRool();
 
 rool.init();              // Process auth callbacks (call on app startup)
 rool.login('My App');     // Redirect to login page
-rool.logout();            // Clear auth state and close all spaces
+rool.logout();            // Clear auth state and close all channels
 rool.destroy();           // Clean up all resources
 ```
 
@@ -118,60 +118,108 @@ Reactive cross-device storage for user preferences. Synced from server on `init(
 </button>
 ```
 
-### Opening Spaces
+### Spaces & Channels
 
 ```typescript
-const space = await rool.openSpace('space-id');
-const space = await rool.openSpace('space-id', { conversationId: 'my-convo' });
+// Open a channel — reactive, with SSE
+const channel = await rool.openChannel('space-id', 'my-channel');
+
+// Create a space, then open a channel on it
 const space = await rool.createSpace('My New Space');
+const channel = await space.openChannel('main');
+
+// Open a space for admin operations (lightweight, no SSE)
+const space = await rool.openSpace('space-id');
+await space.rename('New Name');
+await space.addUser(userId, 'editor');
 
-// Multiple spaces can be open at once
-const spaceA = await rool.openSpace('space-a');
-const spaceB = await rool.openSpace('space-b');
+// Delete a space
+await rool.deleteSpace('space-id');
+
+// Import a space from a zip archive
+const space = await rool.importArchive('Imported', archiveBlob);
 
 // Clean up
-space.close();
+channel.close();
 ```
 
-### ReactiveSpace
+### ReactiveChannel
 
-`openSpace` and `createSpace` return a `ReactiveSpace` — the SDK's `RoolSpace` with reactive `interactions`:
+`openChannel` returns a `ReactiveChannel` — the SDK's `RoolChannel` with reactive `interactions`:
 
 ```svelte
 <script>
-  let space = $state(null);
+  let channel = $state(null);
 
-  async function open(id) {
-    space = await rool.openSpace(id);
+  async function open(spaceId) {
+    channel = await rool.openChannel(spaceId, 'main');
   }
 </script>
 
-{#if space}
+{#if channel}
   <!-- Reactive: updates as AI makes tool calls -->
-  {#each space.interactions as interaction}
+  {#each channel.interactions as interaction}
     <div>
       <strong>{interaction.operation}</strong>: {interaction.output}
     </div>
   {/each}
 
   <!-- All SDK methods work directly -->
-  <button onclick={() => space.prompt('Hello')}>Send</button>
+  <button onclick={() => channel.prompt('Hello')}>Send</button>
 {/if}
 ```
 
-### Reactive Collections
+### Reactive Object
 
-Create auto-updating collections of objects filtered by field values:
+Track a single object by ID with auto-updates:
 
 ```svelte
 <script>
-  let space = $state(null);
+  let channel = $state(null);
+  let item = $state(null);
+
+  async function open(spaceId, objectId) {
+    channel = await rool.openChannel(spaceId, 'main');
+    item = channel.object(objectId);
+  }
+</script>
+
+{#if item}
+  {#if item.loading}
+    <p>Loading...</p>
+  {:else if item.data}
+    <div>{item.data.title}</div>
+  {:else}
+    <p>Object not found</p>
+  {/if}
+{/if}
+```
+
+```typescript
+// Reactive state
+item.data      // $state<RoolObject | undefined>
+item.loading   // $state<boolean>
+
+// Methods
+item.refresh() // Manual re-fetch
+item.close()   // Stop listening for updates
+```
+
+**Lifecycle:** Reactive objects are tied to their channel. Closing the channel stops all updates — existing reactive objects will retain their last data but no longer refresh. Calling `channel.object()` after `close()` throws.
+
+### Reactive Watches
+
+Create auto-updating watches of objects filtered by field values:
+
+```svelte
+<script>
+  let channel = $state(null);
   let articles = $state(null);
 
-  async function open(id) {
-    space = await rool.openSpace(id);
-    // Create a reactive collection of all objects where type === 'article'
-    articles = space.collection({ where: { type: 'article' } });
+  async function open(spaceId) {
+    channel = await rool.openChannel(spaceId, 'main');
+    // Create a reactive watch of all objects where type === 'article'
+    articles = channel.watch({ where: { type: 'article' } });
   }
 </script>
 
@@ -186,11 +234,13 @@ Create auto-updating collections of objects filtered by field values:
 {/if}
 ```
 
-Collections automatically re-fetch when objects matching the filter are created, updated, or deleted. Since the SDK caches objects locally, re-fetches are typically instant (no network round-trip).
+Watches automatically re-fetch when objects matching the filter are created, updated, or deleted. Since the SDK caches objects locally, re-fetches are typically instant (no network round-trip).
+
+**Lifecycle:** Watches are tied to their channel. Closing the channel stops all updates — existing watches will retain their last data but no longer refresh. Calling `channel.watch()` after `close()` throws.
 
 ```typescript
-// Collection options (same as findObjects, but no AI prompt)
-const articles = space.collection({
+// Watch options (same as findObjects, but no AI prompt)
+const articles = channel.watch({
   where: { type: 'article', status: 'published' },
   order: 'desc',  // by modifiedAt (default)
   limit: 20,
@@ -205,36 +255,92 @@ articles.refresh() // Manual re-fetch
 articles.close()   // Stop listening for updates
 ```
 
+### Reactive Channel List
+
+List channels for a space with auto-updates:
+
+```svelte
+<script>
+  const channelList = rool.channels('space-id');
+
+  // Clean up when done
+  import { onDestroy } from 'svelte';
+  onDestroy(() => channelList.close());
+</script>
+
+{#if channelList.loading}
+  <p>Loading channels...</p>
+{:else}
+  {#each channelList.list as ch}
+    <button onclick={() => openChannel(ch.id)}>{ch.name ?? ch.id}</button>
+  {/each}
+{/if}
+```
+
+```typescript
+// Reactive state
+channelList.list      // $state<ChannelInfo[]>
+channelList.loading   // $state<boolean>
+
+// Methods
+channelList.refresh() // Manual re-fetch
+channelList.close()   // Stop listening for updates
+```
+
+### Channel Management
+
+```typescript
+// Rename a channel (thin GraphQL call, no SSE needed)
+await rool.renameChannel('space-id', 'channel-id', 'New Name');
+
+// Delete a channel
+await rool.deleteChannel('space-id', 'channel-id');
+
+// Rename from within a channel
+await channel.rename('New Name');
+```
+
 ### Using the SDK
 
-All `RoolSpace` methods and properties are available on `ReactiveSpace`:
+All `RoolChannel` methods and properties are available on `ReactiveChannel`:
 
 ```typescript
 // Properties
-space.id
-space.name
-space.role
-space.conversationId
+channel.id
+channel.name
+channel.role
+channel.channelId
 
 // Object operations
-await space.getObject(id)
-await space.createObject({ data: { type: 'note', text: 'Hello' } })
-await space.updateObject(id, { data: { text: 'Updated' } })
-await space.deleteObjects([id])
-await space.findObjects({ where: { type: 'note' } })
+await channel.getObject(id)
+await channel.createObject({ data: { type: 'note', text: 'Hello' } })
+await channel.updateObject(id, { data: { text: 'Updated' } })
+await channel.deleteObjects([id])
+await channel.findObjects({ where: { type: 'note' } })
 
 // AI
-await space.prompt('Summarize everything')
+await channel.prompt('Summarize everything')
+
+// Schema
+channel.getSchema()
+await channel.createCollection('article', [
+  { name: 'title', type: { kind: 'string' } },
+  { name: 'status', type: { kind: 'enum', values: ['draft', 'published'] } },
+])
+await channel.alterCollection('article', [...updatedProps])
+await channel.dropCollection('article')
 
 // Undo/Redo
-await space.checkpoint('Before edit')
-await space.undo()
-await space.redo()
-
-// Conversations
-await space.setSystemInstruction('You are helpful')
-await space.renameConversation('id', 'Research')
-space.getInteractions()
+await channel.checkpoint('Before edit')
+await channel.undo()
+await channel.redo()
+
+// Interaction history
+await channel.setSystemInstruction('You are helpful')
+channel.getInteractions()
+
+// Channel admin
+await channel.rename('New Name')
 ```
 
 See the [SDK documentation](../sdk/README.md) for complete API details.
@@ -252,21 +358,26 @@ const id = generateId();
 
 ```typescript
 // Package types
-import type { Rool, ReactiveSpace, ReactiveCollection, CollectionOptions } from '@rool-dev/svelte';
+import type { Rool, ReactiveChannel, ReactiveObject, ReactiveWatch, WatchOptions, ReactiveChannelList } from '@rool-dev/svelte';
 
 // Re-exported from @rool-dev/sdk
 import type {
+  RoolChannel,
   RoolSpace,
   RoolSpaceInfo,
   RoolObject,
   RoolUserRole,
   ConnectionState,
-  ConversationInfo,
+  ChannelInfo,
   Interaction,
   FindObjectsOptions,
   PromptOptions,
   CreateObjectOptions,
   UpdateObjectOptions,
+  FieldType,
+  FieldDef,
+  CollectionDef,
+  SpaceSchema,
 } from '@rool-dev/svelte';
 ```
 

package/dist/channel.svelte.d.ts

@@ -0,0 +1,143 @@
+import type { RoolChannel, RoolClient, Interaction, RoolObject, ChannelInfo } from '@rool-dev/sdk';
+/**
+ * Options for creating a reactive watch.
+ * Same as FindObjectsOptions but without `prompt` (AI queries are too slow for reactive updates).
+ */
+export interface WatchOptions {
+    /** Field requirements for exact matching */
+    where?: Record<string, unknown>;
+    /** Maximum number of objects */
+    limit?: number;
+    /** Sort order by modifiedAt: 'asc' or 'desc' (default: 'desc') */
+    order?: 'asc' | 'desc';
+}
+/**
+ * A reactive watch of objects that auto-updates when matching objects change.
+ */
+declare class ReactiveWatchImpl {
+    #private;
+    objects: RoolObject[];
+    loading: boolean;
+    constructor(channel: RoolChannel, options: WatchOptions);
+    /**
+     * Re-fetch the watched objects from the channel.
+     */
+    refresh(): Promise<void>;
+    /**
+     * Stop listening for updates and clean up.
+     */
+    close(): void;
+}
+export type ReactiveWatch = ReactiveWatchImpl;
+/**
+ * A reactive single object that auto-updates when the object changes.
+ */
+declare class ReactiveObjectImpl {
+    #private;
+    data: RoolObject | undefined;
+    loading: boolean;
+    constructor(channel: RoolChannel, objectId: string);
+    /**
+     * Re-fetch the object from the channel.
+     */
+    refresh(): Promise<void>;
+    /**
+     * Stop listening for updates and clean up.
+     */
+    close(): void;
+}
+export type ReactiveObject = ReactiveObjectImpl;
+/**
+ * Minimal wrapper that adds reactive `interactions` to RoolChannel.
+ * All other properties and methods are proxied to the underlying channel.
+ */
+declare class ReactiveChannelImpl {
+    #private;
+    interactions: Interaction[];
+    constructor(channel: RoolChannel);
+    get id(): string;
+    get name(): string;
+    get role(): import("@rool-dev/sdk").RoolUserRole;
+    get userId(): string;
+    get channelId(): string;
+    get isReadOnly(): boolean;
+    get linkAccess(): import("@rool-dev/sdk").LinkAccess;
+    close(): void;
+    getObject(...args: Parameters<RoolChannel['getObject']>): Promise<RoolObject | undefined>;
+    stat(...args: Parameters<RoolChannel['stat']>): import("@rool-dev/sdk").RoolObjectStat | undefined;
+    findObjects(...args: Parameters<RoolChannel['findObjects']>): Promise<{
+        objects: RoolObject[];
+        message: string;
+    }>;
+    getObjectIds(...args: Parameters<RoolChannel['getObjectIds']>): string[];
+    createObject(...args: Parameters<RoolChannel['createObject']>): Promise<{
+        object: RoolObject;
+        message: string;
+    }>;
+    updateObject(...args: Parameters<RoolChannel['updateObject']>): Promise<{
+        object: RoolObject;
+        message: string;
+    }>;
+    deleteObjects(...args: Parameters<RoolChannel['deleteObjects']>): Promise<void>;
+    prompt(...args: Parameters<RoolChannel['prompt']>): Promise<{
+        message: string;
+        objects: RoolObject[];
+    }>;
+    checkpoint(...args: Parameters<RoolChannel['checkpoint']>): Promise<string>;
+    canUndo(): Promise<boolean>;
+    canRedo(): Promise<boolean>;
+    undo(): Promise<boolean>;
+    redo(): Promise<boolean>;
+    clearHistory(): Promise<void>;
+    setMetadata(...args: Parameters<RoolChannel['setMetadata']>): void;
+    getMetadata(...args: Parameters<RoolChannel['getMetadata']>): unknown;
+    getAllMetadata(): Record<string, unknown>;
+    getInteractions(): Interaction[];
+    getSystemInstruction(): string | undefined;
+    setSystemInstruction(...args: Parameters<RoolChannel['setSystemInstruction']>): Promise<void>;
+    getSchema(): import("@rool-dev/sdk").SpaceSchema;
+    createCollection(...args: Parameters<RoolChannel['createCollection']>): Promise<import("@rool-dev/sdk").CollectionDef>;
+    alterCollection(...args: Parameters<RoolChannel['alterCollection']>): Promise<import("@rool-dev/sdk").CollectionDef>;
+    dropCollection(...args: Parameters<RoolChannel['dropCollection']>): Promise<void>;
+    uploadMedia(...args: Parameters<RoolChannel['uploadMedia']>): Promise<string>;
+    fetchMedia(...args: Parameters<RoolChannel['fetchMedia']>): Promise<import("@rool-dev/sdk").MediaResponse>;
+    deleteMedia(...args: Parameters<RoolChannel['deleteMedia']>): Promise<void>;
+    listMedia(): Promise<import("@rool-dev/sdk").MediaInfo[]>;
+    rename(...args: Parameters<RoolChannel['rename']>): Promise<void>;
+    on(...args: Parameters<RoolChannel['on']>): () => void;
+    off(...args: Parameters<RoolChannel['off']>): void;
+    /**
+     * Create a reactive object that auto-updates when the object changes.
+     * Throws if the channel has been closed.
+     */
+    object(objectId: string): ReactiveObject;
+    /**
+     * Create a reactive watch that auto-updates when matching objects change.
+     * Throws if the channel has been closed.
+     */
+    watch(options: WatchOptions): ReactiveWatch;
+}
+export declare function wrapChannel(channel: RoolChannel): ReactiveChannel;
+export type ReactiveChannel = ReactiveChannelImpl;
+/**
+ * A reactive list of channels for a space that auto-updates via SSE events.
+ */
+declare class ReactiveChannelListImpl {
+    #private;
+    list: ChannelInfo[];
+    loading: boolean;
+    constructor(client: RoolClient, spaceId: string);
+    /**
+     * Re-fetch the channel list from the server.
+     * Opens a lightweight space handle to get the channel list.
+     */
+    refresh(): Promise<void>;
+    /**
+     * Stop listening for updates and clean up.
+     */
+    close(): void;
+}
+export declare function createChannelList(client: RoolClient, spaceId: string): ReactiveChannelList;
+export type ReactiveChannelList = ReactiveChannelListImpl;
+export {};
+//# sourceMappingURL=channel.svelte.d.ts.map

package/dist/channel.svelte.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"channel.svelte.d.ts","sourceRoot":"","sources":["../src/channel.svelte.ts"],"names":[],"mappings":"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"}