@rool-dev/client 0.3.0-dev.f9b91b8 → 0.3.1-dev.34258b6

package/README.md

@@ -13,11 +13,11 @@ npm install @rool-dev/client
 ```typescript
 import { RoolClient } from '@rool-dev/client';
 
-const client = new RoolClient({ baseUrl: 'https://use.rool.dev/rool-server' });
-client.initialize();
+const client = new RoolClient({ baseUrl: 'https://use.rool.dev' });
+client.initialize();  // Process auth callback if returning from login
 
 if (!client.isAuthenticated()) {
-  client.login(); // Redirects to auth page
+  client.login();  // Redirects to auth page
 }
 
 // Subscribe to real-time events
@@ -27,16 +27,16 @@ await client.subscribe();
 const graph = await client.openGraph('my-graph-id');
 graph.subscribe(); // Listen for real-time updates
 
-// Add a node
-graph.checkpoint('Add node');
-graph.addNode('node1', { type: 'text', content: 'Hello' });
+// Create an object
+graph.checkpoint('Add object');
+const { id } = await graph.createObject({ type: 'text', fields: { content: 'Hello' } });
 
-// Link nodes
-graph.linkNodes('node1', 'node2', 'connection');
+// Create a link between objects
+await graph.link(id, 'object2', 'connection');
 
 // Undo/redo support
-graph.undo();
-graph.redo();
+await graph.undo();
+await graph.redo();
 
 // Clean up
 graph.close();
@@ -46,18 +46,64 @@ graph.close();
 
 ```typescript
 interface RoolClientConfig {
-  baseUrl: string;           // Server URL (see below)
-  storagePrefix?: string;    // localStorage prefix (default: 'rool_')
-  authProvider?: AuthProvider; // Custom auth (e.g., for Electron)
+  baseUrl: string;           // Base URL (e.g., 'https://use.rool.dev')
+  graphqlUrl?: string;       // Override GraphQL endpoint (default: {baseUrl}/graphql)
+  mediaUrl?: string;         // Override media endpoint (default: {baseUrl}/media)
+  authUrl?: string;          // Override auth endpoint (default: {baseUrl}/auth)
+  authProvider?: AuthProvider; // Optional, defaults to browser auth
 }
 ```
 
-### Server URLs
+### Base URLs
 
 | Environment | URL |
 |-------------|-----|
-| Development | `https://use.rool.dev/rool-server` |
-| Production | `https://use.rool.app/rool-server` |
+| Development | `https://use.rool.dev` |
+| Production | `https://use.rool.app` |
+
+### Auth Providers
+
+**Browser (default)** — No configuration needed. Uses localStorage for tokens, redirects to login page.
+
+```typescript
+const client = new RoolClient({ baseUrl: 'https://use.rool.dev' });
+client.initialize(); // Process auth callbacks if this is a callback from the auth page
+
+if (!client.isAuthenticated()) {
+  client.login(); // Redirect to the auth page
+}
+```
+
+**Node.js** — For CLI tools and scripts. Stores credentials in `~/.config/rool/`, opens browser for login.
+
+```typescript
+import { NodeAuthProvider } from '@rool-dev/client/node';
+
+const client = new RoolClient({
+  baseUrl: 'https://use.rool.dev',
+  authProvider: new NodeAuthProvider()
+});
+
+if (!client.isAuthenticated()) {
+  await client.login(); // Open auth page in system browser, await callback
+}
+```
+
+**Custom** — Implement the `AuthProvider` interface for full control.
+
+```typescript
+const client = new RoolClient({
+  baseUrl: 'https://use.rool.dev',
+  authProvider: {
+    initialize: () => false,
+    getToken: async () => myStore.getAccessToken(),
+    getUser: () => ({ email: 'user@example.com', name: 'User' }),
+    isAuthenticated: () => myStore.hasValidToken(),
+    login: async () => { /* your login flow */ },
+    logout: () => myStore.clear(),
+  }
+});
+```
 
 
 ---
@@ -68,7 +114,7 @@ interface RoolClientConfig {
 
 | Method | Description |
 |--------|-------------|
-| `initialize(): boolean` | **Call on app startup.** Processes auth callback from URL, sets up token refresh. |
+| `initialize(): boolean` | **Call on app startup if running in browser.** Processes auth callback from URL, sets up token refresh. |
 | `login(): void` | Redirect to login page |
 | `logout(): void` | Clear tokens and state |
 | `isAuthenticated(): boolean` | Check auth status |
@@ -155,34 +201,70 @@ Graphs are first-class objects with built-in undo/redo, event emission, and real
 | `redo(): Promise<boolean>` | Redo undone action |
 | `clearHistory(): void` | Clear undo/redo stack |
 
-### Node Operations
+### Object Operations
 
 | Method | Description |
 |--------|-------------|
-| `getNode(nodeId): RoolNode` | Get node (throws if not found) |
-| `getNodeOrUndefined(nodeId): RoolNode \| undefined` | Get node or undefined |
-| `getNodesByType(type): RoolNode[]` | Get all nodes of type |
-| `getNodeIds(): string[]` | Get all node IDs |
-| `addNode(nodeId, node): void` | Add a node |
-| `updateNode(nodeId, updates): void` | Update node fields |
-| `deleteNodes(nodeIds): void` | Delete nodes (and connected edges) |
+| `getObject(objectId): RoolObject` | Get object data. Throws if not found. |
+| `getObjectOrUndefined(objectId): RoolObject \| undefined` | Get object data, or undefined if not found. |
+| `getObjectsByType(type): RoolObject[]` | Get all objects matching the given type. |
+| `getObjectIds(): string[]` | Get all object IDs in the graph. |
+| `getObjectMeta(objectId): Record<string, unknown>` | Get object metadata (position, UI state, etc.) Hidden from AI. |
+| `createObject(options): Promise<{ id, message }>` | Create a new object. Returns the generated ID and AI message. |
+| `updateObject(objectId, options): Promise<string>` | Update an existing object. Returns AI message. |
+| `deleteObjects(objectIds): Promise<void>` | Delete objects. Outbound links are removed automatically. |
+
+#### createObject / updateObject Options
+
+Both methods accept an options object:
+
+| Option | Description |
+|--------|-------------|
+| `type` | Object type (required for create, optional for update). |
+| `fields` | Key-value pairs for object data. Use `{{placeholder}}` for AI-generated content. |
+| `meta` | Client-private metadata (e.g., position). Hidden from AI operations. |
+| `prompt` | Natural language instruction for AI to generate or modify content. |
+
+**AI Placeholder Pattern**: Use `{{description}}` in field values to have AI generate content:
+
+```typescript
+// Create with AI-generated content
+await graph.createObject({
+  type: 'article',
+  fields: {
+    headline: '{{catchy headline about coffee}}',
+    body: '{{informative paragraph}}'
+  },
+  prompt: 'Write about specialty coffee brewing'
+});
 
-### Edge Operations
+// Update existing content with AI
+await graph.updateObject('abc123', {
+  prompt: 'Make the body shorter and more casual'
+});
+
+// Add new AI-generated field to existing object
+await graph.updateObject('abc123', {
+  fields: { summary: '{{one-sentence summary}}' }
+});
+```
+
+### Link Operations
+
+Links connect objects directionally. They are stored on the source object and identified by `sourceId + linkType + targetId`.
 
 | Method | Description |
 |--------|-------------|
-| `linkNodes(sourceId, targetId, edgeType): string` | Create edge, returns edge ID |
-| `unlinkNodes(sourceId, targetId): boolean` | Remove edges between nodes |
-| `getParents(nodeId, edgeType?): string[]` | Get nodes pointing to this node |
-| `getChildren(nodeId, edgeType?): string[]` | Get nodes this node points to |
-| `getEdge(edgeId): RoolEdge \| undefined` | Get edge by ID |
-| `getEdgeIds(): string[]` | Get all edge IDs |
+| `link(sourceId, targetId, linkType): Promise<void>` | Create a link from source to target with the given type. |
+| `unlink(sourceId, targetId, linkType?): Promise<boolean>` | Remove link(s). If `linkType` provided, removes only that type; otherwise removes all links between the objects. |
+| `getParents(objectId, linkType?): string[]` | Get IDs of objects that link TO this object. |
+| `getChildren(objectId, linkType?): string[]` | Get IDs of objects this object links TO. |
 
 ### Metadata
 
 | Method | Description |
 |--------|-------------|
-| `setMetadata(key, value): void` | Set metadata (hidden from AI) |
+| `setMetadata(key, value): void` | Set graph-level metadata (hidden from AI) |
 | `getMetadata(key): unknown` | Get metadata value |
 | `getAllMetadata(): Record<string, unknown>` | Get all metadata |
 
@@ -191,8 +273,32 @@ Graphs are first-class objects with built-in undo/redo, event emission, and real
 | Method | Description |
 |--------|-------------|
 | `prompt(prompt, options?): Promise<string \| null>` | AI graph manipulation |
-| `generateImage(prompt, aspectRatio?): Promise<ImageResult>` | Generate AI image |
-| `editImage(prompt, url): Promise<ImageResult>` | Edit image with AI |
+
+The `prompt` method lets you invoke the AI agent to manipulate the graph, perform research, or query information.
+
+**Capabilities:**
+- **Creation**: "Create 3 markdown nodes with haikus about nature"
+- **Modification**: "Make the selected node's text more formal"
+- **Research**: "Create a knowledge graph about the exoplanets orbiting PSR B1257+12" (Agent will search Wikipedia)
+- **Structure**: "Connect the topic node to all created child nodes"
+
+**Options:**
+- `objectIds`: Limit context to specific objects ("Update *these* objects")
+- `responseSchema`: Request a structured JSON response instead of a text summary
+
+```typescript
+// Example: Research and expansion
+await client.prompt(
+  "Create a topic node for the solar system, then child nodes for each planet.",
+  { responseSchema: null } // Returns a text summary
+);
+
+// Example: Focused update
+await client.prompt(
+  "Summarize this article in the 'summary' field",
+  { objectIds: ['article-node-id'] }
+);
+```
 
 ### Collaboration
 
@@ -216,15 +322,30 @@ Graphs are first-class objects with built-in undo/redo, event emission, and real
 
 | Method | Description |
 |--------|-------------|
-| `getData(): RoolGraphData` | Get full graph data |
-| `patch(operations): void` | Apply JSON patch |
+| `getData(): RoolGraphData` | Get full graph data (internal format) |
 
 ### Graph Events
 
+Semantic events describe what changed. Events fire for both local changes and remote changes.
+
 ```typescript
-// Incremental change - ops is the raw JSON patch
-// source indicates origin: 'local' | 'remote_user' | 'remote_agent' | 'system'
-graph.on('patch', ({ ops, source }) => void)
+// source indicates origin:
+// - 'local_user': This client made the change
+// - 'remote_user': Another user/client made the change
+// - 'remote_agent': AI agent made the change
+// - 'system': Resync after error
+
+// Object events
+graph.on('objectCreated', ({ objectId, object, source }) => void)
+graph.on('objectUpdated', ({ objectId, object, source }) => void)
+graph.on('objectDeleted', ({ objectId, source }) => void)
+
+// Link events
+graph.on('linked', ({ sourceId, targetId, linkType, source }) => void)
+graph.on('unlinked', ({ sourceId, targetId, linkType, source }) => void)
+
+// Graph metadata
+graph.on('metaUpdated', ({ meta, source }) => void)
 
 // Full state replacement (undo/redo, resync after error)
 graph.on('reset', ({ source }) => void)
@@ -233,9 +354,19 @@ graph.on('reset', ({ source }) => void)
 graph.on('syncError', (error: Error) => void)
 ```
 
-**Usage patterns:**
-- **Simple (full re-render)**: Listen to both `patch` and `reset`, call `graph.getData()` and re-render
-- **Power user (incremental)**: Parse `ops` in `patch` for granular updates, full re-render on `reset`
+**Usage pattern:**
+```typescript
+// All UI updates happen in one place, regardless of change source
+graph.on('objectUpdated', ({ objectId, object, source }) => {
+  renderObject(objectId, object);
+  if (source === 'remote_agent') {
+    doLayout(); // AI might have added content
+  }
+});
+
+// Caller just makes the change - event handler does the UI work
+graph.updateObject(objectId, { prompt: 'expand this' });
+```
 
 ---
 
@@ -244,24 +375,23 @@ graph.on('syncError', (error: Error) => void)
 ### Graph Data
 
 ```typescript
-interface RoolGraphData {
-  nodes: Record<string, RoolNode>;
-  edges: Record<string, RoolEdge>;
-  _meta: Record<string, unknown>;  // Hidden from AI
-}
-
-interface RoolNode {
+// RoolObject represents the object data you work with
+interface RoolObject {
   type: string;
-  _meta: Record<string, unknown>;
   [key: string]: unknown;
 }
 
-interface RoolEdge {
-  sources: string[];
-  targets: string[];
-  type: string;
-  _meta: Record<string, unknown>;
-  [key: string]: unknown;
+// Internal graph data structure
+interface RoolGraphData {
+  objects: Record<string, ObjectEntry>;
+  meta: Record<string, unknown>;  // Graph-level metadata, hidden from AI
+}
+
+// Internal: Full stored object structure (you typically don't use this directly)
+interface ObjectEntry {
+  meta: Record<string, unknown>;   // Object-level metadata
+  links: Record<string, Record<string, Record<string, unknown>>>;  // linkType -> targetId -> linkData
+  data: RoolObject;                // The actual object data
 }
 ```
 
@@ -275,43 +405,20 @@ interface RoolGraphUser { id: string; email: string; role: RoolGraphRole; }
 interface UserResult { id: string; email: string; }
 interface Account { id: string; email: string; plan: string; creditsBalance: number; }
 interface MediaItem { uuid: string; url: string; contentType: string; size: number; }
-interface ImageResult { url: string; }
-type ImageAspectRatio = '1:1' | '3:4' | '4:3' | '9:16' | '16:9';
-type GraphPatchSource = 'local' | 'remote_user' | 'remote_agent' | 'system';
+type ChangeSource = 'local_user' | 'remote_user' | 'remote_agent' | 'system';
 ```
 
 ### Prompt Options
 
 ```typescript
 interface PromptOptions {
-  nodeIds?: string[];      // Scope to specific nodes
-  edgeIds?: string[];      // Scope to specific edges
-  metadata?: Record<string, unknown>;
+  objectIds?: string[];      // Scope to specific objects
   responseSchema?: Record<string, unknown>;
 }
 ```
 
 ---
 
-## Custom Auth Provider
-
-For Electron or custom auth flows:
-
-```typescript
-const client = new RoolClient({
-  baseUrl: 'https://use.rool.dev',
-  authProvider: {
-    getToken: async () => myTokenStore.getAccessToken(),
-    getUser: () => ({ email: 'user@example.com', name: 'User' }),
-    isAuthenticated: () => myTokenStore.hasValidToken(),
-    login: () => myAuthFlow.startLogin(),
-    logout: () => myTokenStore.clear(),
-  }
-});
-```
-
----
-
 ## License
 
 Proprietary - © Lightpost One. All rights reserved.

package/dist/auth-browser.d.ts

@@ -0,0 +1,71 @@
+import type { AuthProvider, UserInfo } from './types.js';
+export interface BrowserAuthConfig {
+    /** Auth service URL (e.g. https://use.rool.dev/auth) */
+    authUrl: string;
+    storagePrefix?: string;
+    onAuthStateChanged: (authenticated: boolean) => void;
+}
+export declare class BrowserAuthProvider implements AuthProvider {
+    private config;
+    private apiKey;
+    private apiKeyFetchPromise;
+    private refreshPromise;
+    private refreshTimeoutId;
+    private get storageKeys();
+    /** Auth URL without trailing slash */
+    private get authBaseUrl();
+    constructor(config: BrowserAuthConfig);
+    /**
+     * Initialize auth manager - should be called on app startup.
+     * Processes any auth callback in the URL and sets up auto-refresh.
+     */
+    initialize(): boolean;
+    /**
+     * Check if user is currently authenticated (has valid token).
+     */
+    isAuthenticated(): boolean;
+    /**
+     * Get current access token, refreshing if expired.
+     * Returns undefined if not authenticated.
+     */
+    getToken(): Promise<string | undefined>;
+    /**
+     * Get user info decoded from JWT token.
+     */
+    getUser(): UserInfo;
+    /**
+     * Initiate login by redirecting to auth page.
+     */
+    login(): void;
+    /**
+     * Logout - clear all tokens and state.
+     */
+    logout(): void;
+    /**
+     * Process auth callback from URL fragment.
+     * Should be called on page load.
+     * @returns true if callback was processed
+     */
+    processCallback(): boolean;
+    /**
+     * Destroy auth manager - clear refresh timers.
+     */
+    destroy(): void;
+    /**
+     * Get the API key, fetching from server if not provided in config.
+     */
+    private getApiKey;
+    private tryRefreshToken;
+    private scheduleTokenRefresh;
+    private cancelScheduledRefresh;
+    private readAccessToken;
+    private readExpiresAt;
+    private writeTokens;
+    private clearTokens;
+    private storeState;
+    private readState;
+    private clearState;
+    private generateState;
+    private decodeUserInfo;
+}
+//# sourceMappingURL=auth-browser.d.ts.map

package/dist/auth-browser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-browser.d.ts","sourceRoot":"","sources":["../src/auth-browser.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAOzD,MAAM,WAAW,iBAAiB;IAC9B,wDAAwD;IACxD,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,kBAAkB,EAAE,CAAC,aAAa,EAAE,OAAO,KAAK,IAAI,CAAC;CACxD;AAED,qBAAa,mBAAoB,YAAW,YAAY;IACpD,OAAO,CAAC,MAAM,CAAoB;IAClC,OAAO,CAAC,MAAM,CAAuB;IACrC,OAAO,CAAC,kBAAkB,CAAuC;IACjE,OAAO,CAAC,cAAc,CAAiC;IACvD,OAAO,CAAC,gBAAgB,CAA8C;IAEtE,OAAO,KAAK,WAAW,GAQtB;IAED,sCAAsC;IACtC,OAAO,KAAK,WAAW,GAEtB;gBAEW,MAAM,EAAE,iBAAiB;IAIrC;;;OAGG;IACH,UAAU,IAAI,OAAO;IAMrB;;OAEG;IACH,eAAe,IAAI,OAAO;IAO1B;;;OAGG;IACG,QAAQ,IAAI,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;IAgB7C;;OAEG;IACH,OAAO,IAAI,QAAQ;IAMnB;;OAEG;IACH,KAAK,IAAI,IAAI;IAYb;;OAEG;IACH,MAAM,IAAI,IAAI;IAOd;;;;OAIG;IACH,eAAe,IAAI,OAAO;IAyC1B;;OAEG;IACH,OAAO,IAAI,IAAI;IAQf;;OAEG;YACW,SAAS;YAgCT,eAAe;IA4E7B,OAAO,CAAC,oBAAoB;IAmB5B,OAAO,CAAC,sBAAsB;IAO9B,OAAO,CAAC,eAAe;IAIvB,OAAO,CAAC,aAAa;IAOrB,OAAO,CAAC,WAAW;IAwBnB,OAAO,CAAC,WAAW;IAInB,OAAO,CAAC,UAAU;IAQlB,OAAO,CAAC,SAAS;IAQjB,OAAO,CAAC,UAAU;IAQlB,OAAO,CAAC,aAAa;IAUrB,OAAO,CAAC,cAAc;CAYzB"}