@ilivemylife/graph-sdk 1.0.0

package/README.md

@@ -0,0 +1,725 @@
+# @ilivemylife/graph-sdk
+
+SDK for [iLiveMyLife](https://iLiveMyLife.io) Knowledge Graph.
+
+## What is iLiveMyLife?
+
+**iLiveMyLife** is your personal **informational wallet** — a unified platform to organize everything in your life.
+
+### Key Features
+
+- **Knowledge Graph** — Structure your information as interconnected nodes, not just files and folders
+- **Cross-platform** — Apps for iOS, Android, Web, Desktop (macOS, Windows, Linux)
+- **Real-time Sync** — Changes sync instantly across all your devices
+- **Push Notifications** — Stay informed with smart notifications
+- **Team Collaboration** — Share nodes with team members, control privacy with tags (private/wallet/kyc/etc.)
+- **AI Assistants (Lifebot)** — Built-in AI that understands your knowledge graph context
+- **Offline Support** — Your data is synced on your device for offline access if not connected
+- **Powerful Tags System** — Customize node behavior with tags (privacy, AI assistance, colors, markers, and more)
+- **Markers (Status System)** — Track item status with customizable markers (like task states)
+- **Rich Content** — Support for text, images, files, links, checklists, due dates, and more
+- **Robust API & SDK** — Full-featured TypeScript SDK and GraphQL API for developers
+- **CLI Tool** — Command-line interface for scripting and automation
+- **MCP Server** — Integrate with AI assistants like Claude, Cursor, Windsurf via Model Context Protocol
+
+### Use Cases
+
+- Personal knowledge management
+- Team project coordination
+- Task and goal tracking
+- Note-taking with AI assistance
+- Information organization for any domain
+
+**Get the app:** [https://iLiveMyLife.io](https://iLiveMyLife.io)
+
+---
+
+## Prerequisites
+
+- **Node.js 18+** — [download](https://nodejs.org/)
+- **iLiveMyLife account** — sign up at [iLiveMyLife.io](https://iLiveMyLife.io)
+
+## Installation
+
+```bash
+npm install @ilivemylife/graph-sdk
+```
+
+## Authentication
+
+You need an access token to use the SDK.
+
+**Option 1: CLI Login (recommended)**
+```bash
+npx ilml login
+# Prompts for email and password in terminal
+# Token saved to ~/.ilivemylife/config.json
+# After this, CLI commands work automatically
+# For SDK, pass token explicitly: createGraphClient({ token })
+```
+
+**Option 2: Programmatic login (for bots and automations)**
+```javascript
+const response = await fetch('https://api.ilivemylife.io/api/v1/login', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ email: 'you@example.com', password: '...' })
+});
+const token = response.headers.get('access-token');
+
+const graph = createGraphClient({ token });
+```
+
+**Option 3: Browser DevTools (manual)**
+1. Open https://app.ilivemylife.io and log in
+2. Open DevTools (F12) → Network tab
+3. Make any action (refresh page, open a node)
+4. Click any GraphQL request → Headers tab
+5. Copy `access-token` value, use it as: `createGraphClient({ token: 'copied-value' })`
+
+### Config File
+
+After `ilml login`, config is saved as JSON:
+
+```json
+// ~/.ilivemylife/config.json
+{
+  "token": "your-access-token",
+  "user": {
+    "id": "user-id",
+    "email": "you@example.com",
+    "displayName": "Your Name"
+  },
+  "rootItemId": "your-root-node-id"
+}
+```
+
+- `token` — access token for API requests
+- `user` — your account info (cached for display in CLI)
+- `rootItemId` — your "My Life" root node ID
+
+### Token Priority
+
+The SDK and CLI resolve tokens in this order (first found wins):
+
+| Priority | Source | How to set |
+|----------|--------|------------|
+| 1 | Local config | `ilml login --local` → `.ilivemylife/config.json` in project dir |
+| 2 | `.env` file | Create `.env` with `ILML_TOKEN=your-token` in project dir |
+| 3 | Global config | `ilml login` → `~/.ilivemylife/config.json` |
+| 4 | Environment variable | `export ILML_TOKEN=your-token` |
+
+This lets you use different accounts per project:
+```bash
+# Global account (default)
+ilml login
+
+# Project-specific account (overrides global)
+cd my-project
+ilml login --local
+
+# Or via .env file
+echo "ILML_TOKEN=project-specific-token" > .env
+```
+
+## Finding Node IDs
+
+Node IDs are visible in the URL when viewing a node:
+```
+https://app.ilivemylife.io/item/00001191f13c5c81-ee4ae8284f820001
+                                ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+                                 This is the node ID
+```
+
+Or get your root node ("My Life") programmatically:
+```javascript
+const me = await graph.me();
+console.log(me.rootItemId);  // Your root node ID
+```
+
+## Quick Start
+
+```javascript
+import { createGraphClient } from '@ilivemylife/graph-sdk';
+
+// Create client (token from ilml login or env variable)
+const graph = createGraphClient({
+    token: process.env.ILML_TOKEN
+});
+
+// Get your root node
+const me = await graph.me();
+const rootId = me.rootItemId;
+
+// See what's in your graph
+const items = await graph.items(rootId);
+console.log('My Life:', items[0].title);
+console.log('Children:', items.slice(1).map(i => i.title));
+
+// Create a new node
+const project = await graph.addItem(rootId, { title: 'My Project' });
+
+// Add children to it
+await graph.addItem(project.id, { title: 'First Task' });
+await graph.addItem(project.id, { title: 'Second Task' });
+
+// Ask AI about it (requires 'assist' tag on the node)
+const reply = await graph.askLifebot(project.id, 'What tasks do I have?');
+console.log(reply.content);
+```
+
+For a complete walkthrough, run: `node examples/getting-started.mjs`
+
+## Features
+
+- **TypeScript** — Full type definitions included
+- **Dual Format** — Works with both ESM (`import`) and CommonJS (`require`)
+- **Typed Errors** — `GraphError`, `LifebotTimeoutError`, `LifebotRateLimitError`
+- **Injectable Logger** — Pass your own logger or use silent mode
+- **Real-time Subscriptions** — Subscribe to message and item changes
+
+## Examples
+
+See [examples/](./examples/) directory for complete usage examples:
+
+- [getting-started.mjs](./examples/getting-started.mjs) — **Start here!** Complete walkthrough (no NODE_ID needed)
+- [messenger-basics.mjs](./examples/messenger-basics.mjs) — Messages and Lifebot AI
+- [ask-lifebot.mjs](./examples/ask-lifebot.mjs) — AI interactions with error handling
+- [manage-items.mjs](./examples/manage-items.mjs) — Create, edit, reorder items
+- [subscriptions.mjs](./examples/subscriptions.mjs) — Real-time updates
+- [error-handling.mjs](./examples/error-handling.mjs) — Error handling patterns
+
+---
+
+## API Reference
+
+### Creating a Client
+
+```javascript
+import { createGraphClient } from '@ilivemylife/graph-sdk';
+
+const graph = createGraphClient({
+    token: 'your-access-token',      // Required
+    logger: console                   // Optional: enable logging
+});
+```
+
+### Queries (Read Operations)
+
+```javascript
+// Get node and its children
+const items = await graph.items(nodeId);
+// items[0] = node itself, items[1...n] = children
+
+// Get messages
+const messages = await graph.messages(nodeId, 20);
+
+// Get change history
+const history = await graph.itemHistory(nodeId);
+
+// Get users with access
+const users = await graph.itemUsers(nodeId);
+
+// Get child count
+const { count } = await graph.subItemCount(nodeId);
+
+// Get node settings
+const settings = await graph.itemSettings(nodeId);
+
+// Search messages
+const found = await graph.searchMessages(nodeId, 'keyword');
+```
+
+### Mutations (Write Operations)
+
+```javascript
+// Create item (all fields optional, node added to end of list by default)
+const item = await graph.addItem(parentId, {
+    title: 'New Item',
+    description: 'Description',
+    tags: ['tag1', 'tag2'],
+    dueDate: '1735689600000'  // timestamp string (ms)
+});
+
+// Create link/shortcut to another node
+const link = await graph.addItem(parentId, {
+    refId: originalNodeId,        // reference to original node
+    title: 'Custom Title',        // override original title
+    description: 'Custom Desc'    // override original description
+});
+
+// Edit item
+await graph.editItem({
+    id: itemId,
+    title: 'Updated Title'
+});
+
+// Archive/unarchive
+await graph.archiveItem(itemId);
+await graph.unarchiveItem(itemId);
+
+// Move item to different parent
+await graph.moveItem(itemId, fromParentId, toParentId);
+
+// Reorder within parent (positions are 1-based)
+await graph.reorderChild(parentId, fromPosition, toPosition);
+// Example: move child from position 4 to position 1
+await graph.reorderChild(parentId, 4, 1);
+
+// Move specific node to position (positions are 1-based)
+await graph.setPosition(nodeId, parentId, position);
+// Example: move node to position 2
+await graph.setPosition(nodeId, parentId, 2);
+```
+
+### Messages
+
+```javascript
+import { LIFEBOT_MESSAGE_TYPES, MESSAGE_TYPES } from '@ilivemylife/graph-sdk';
+
+// Simple message (no AI)
+await graph.addMessage(nodeId, 'Hello!', {
+    lifebot: LIFEBOT_MESSAGE_TYPES.off
+});
+
+// Message that triggers AI response
+await graph.addMessage(nodeId, 'Help me with this', {
+    lifebot: LIFEBOT_MESSAGE_TYPES.on
+});
+
+// Reply to a message
+await graph.addMessage(nodeId, 'Thanks!', {
+    type: MESSAGE_TYPES.reply,
+    refId: originalMessageId
+});
+
+// Edit/archive messages
+await graph.editMessage({ id: msgId, content: 'Updated' });
+await graph.archiveMessage(msgId);
+```
+
+### Real-time Subscriptions
+
+```javascript
+import { MESSAGE_CHANGE_TYPES, ITEM_CHANGE_TYPES } from '@ilivemylife/graph-sdk';
+
+// Subscribe to messages
+const unsubscribeMessages = await graph.subscribeToMessages(nodeId, (change, message) => {
+    if (change === MESSAGE_CHANGE_TYPES.added) {
+        console.log('New message:', message.content);
+    } else if (change === MESSAGE_CHANGE_TYPES.edited) {
+        console.log('Message edited:', message.content);
+    } else if (change === MESSAGE_CHANGE_TYPES.deleted) {
+        console.log('Message deleted:', message.id);
+    }
+});
+
+// Subscribe to item changes
+const unsubscribeItems = await graph.subscribeToItems(nodeId, (change, item) => {
+    if (change === ITEM_CHANGE_TYPES.added) {
+        console.log('New item:', item.title);
+    } else if (change === ITEM_CHANGE_TYPES.movedIn) {
+        console.log('Item moved here:', item.title);
+    } else if (change === ITEM_CHANGE_TYPES.reorder) {
+        console.log('Item reordered:', item.title);
+    }
+});
+
+// Stop listening
+unsubscribeMessages();
+unsubscribeItems();
+
+// Wait for specific message
+const msg = await graph.waitForMessage(nodeId,
+    (change, msg) => change === MESSAGE_CHANGE_TYPES.added && msg.createdBy === 'Lifebot',
+    30000  // timeout
+);
+
+// Wait for any reply after your message
+const reply = await graph.waitForReply(nodeId, myMessageId);
+
+// Wait for a reply that directly references your message (via refId)
+const exactReply = await graph.waitForReply(nodeId, myMessageId, { exactMatch: true, timeout: 60000 });
+```
+
+### AI Interactions
+
+```javascript
+import { LifebotTimeoutError, LifebotRateLimitError } from '@ilivemylife/graph-sdk';
+
+try {
+    const response = await graph.askLifebot(nodeId, 'What is 2 + 2?', {
+        timeout: 60000  // 60 seconds
+    });
+    console.log(response.content);
+} catch (error) {
+    if (error instanceof LifebotTimeoutError) {
+        console.error('AI did not respond in time');
+    } else if (error instanceof LifebotRateLimitError) {
+        console.error('Rate limit exceeded');
+    }
+}
+```
+
+**What is Lifebot?**
+
+Lifebot is the AI assistant that lives inside your iLiveMyLife knowledge graph. It can:
+- Answer questions about your data and context
+- Search and find information across your nodes
+- **Create new nodes** with titles and descriptions
+- **Organize information** by creating nested structure
+- Execute actions on your behalf
+
+```javascript
+// Ask Lifebot to create a project with sub-tasks
+await graph.askLifebot(nodeId,
+    'Create a node "Weekly Plan" with 3 tasks inside: Monday review, Wednesday sync, Friday summary'
+);
+// Lifebot will create the parent node AND all children!
+```
+
+**Enable Lifebot:** Add `assist` tag to a node to enable Lifebot in that context.
+
+### Helper Methods
+
+```javascript
+// Get single item
+const item = await graph.getItem(nodeId);
+
+// Resolve reference (shortcut) to actual node
+const actual = await graph.resolveRef(nodeId);
+
+// Get items with references resolved
+const items = await graph.itemsResolved(nodeId);
+```
+
+### Cleanup
+
+```javascript
+// Close all connections and free resources when done
+graph.destroy();
+```
+
+Call `destroy()` at the end of scripts to close WebSocket connections and let the process exit. Safe to call multiple times. Not needed for HTTP-only usage (queries/mutations without subscriptions).
+
+### Validation
+
+```javascript
+import { isValidNodeId, parseNodeId, validateNodeId } from '@ilivemylife/graph-sdk';
+
+// Check if string is valid node ID
+isValidNodeId('00001191f13c5c81-ee4ae8284f820001') // true
+isValidNodeId('invalid') // false
+
+// Parse node ID from raw ID or full URL
+parseNodeId('00001191f13c5c81-ee4ae8284f820001')
+// → '00001191f13c5c81-ee4ae8284f820001'
+
+parseNodeId('https://app.ilivemylife.io/item/00001191f13c5c81-ee4ae8284f820001')
+// → '00001191f13c5c81-ee4ae8284f820001'
+
+parseNodeId('invalid')
+// → null
+
+// Validate and throw error if invalid
+validateNodeId(userInput); // throws GraphError if invalid
+```
+
+### REST API
+
+```javascript
+// Login
+const { user, accessToken } = await graph.login(email, password);
+
+// Get current user
+const me = await graph.me();
+```
+
+---
+
+## Error Handling
+
+```javascript
+import {
+    GraphError,           // Base error
+    GraphNetworkError,    // Network/connection issues
+    GraphAuthError,       // Authentication failed
+    LifebotError,         // AI error base
+    LifebotTimeoutError,  // AI timeout
+    LifebotRateLimitError // AI rate limit
+} from '@ilivemylife/graph-sdk';
+
+try {
+    await graph.addItem(nodeId, { title: 'Test' });
+} catch (error) {
+    if (error instanceof GraphAuthError) {
+        console.error('Check your token');
+    } else if (error instanceof GraphError) {
+        console.error('Operation failed:', error.code);
+    }
+}
+```
+
+---
+
+## Constants
+
+```javascript
+import {
+    // Message options
+    MESSAGE_TYPES,         // normal, reply, forward
+    LIFEBOT_MESSAGE_TYPES, // on, off
+    NOTIFY_MESSAGE_TYPES,  // on, off, postpone
+
+    // Subscription change types
+    MESSAGE_CHANGE_TYPES,  // added ('+1'), edited ('edit'), deleted ('-1')
+    ITEM_CHANGE_TYPES,     // added ('+1'), edited ('edit'), deleted ('-1'), movedIn ('movedIn'), reorder ('reorder')
+
+    // Access and settings
+    ITEM_ACCESS_TYPES,     // human, bot, request
+    AI_PROVIDER_TYPES,     // openai, claude, gemini
+    NODE_SPECIAL_TYPES     // user_settings, user_system, non_drop
+} from '@ilivemylife/graph-sdk';
+
+// Subscription change values:
+// MESSAGE_CHANGE_TYPES.added   === '+1'
+// MESSAGE_CHANGE_TYPES.edited  === 'edit'
+// MESSAGE_CHANGE_TYPES.deleted === '-1'
+//
+// ITEM_CHANGE_TYPES.added      === '+1'
+// ITEM_CHANGE_TYPES.edited     === 'edit'
+// ITEM_CHANGE_TYPES.deleted    === '-1'
+// ITEM_CHANGE_TYPES.movedIn    === 'movedIn'
+// ITEM_CHANGE_TYPES.reorder    === 'reorder'
+```
+
+---
+
+## Tags & Markers
+
+Tags control node behavior. Format: `#tagname#value` or just `tagname`.
+
+### Special Tags
+
+| Tag | Description |
+|-----|-------------|
+| `wallet` | High privacy — entering the node requires access. Hidden from AI completely (invisible in search, context, and responses). Can be shared between users (e.g. corporate wallet between CEO and accountant) by granting access. **Known limitation:** currently wallet nodes are still visible (title, description) in parent's children list and in messenger link previews to users without access. This will be fixed — wallet nodes should be completely invisible to unauthorized users |
+| `private` | Lower privacy — node itself is visible but entering (seeing children) requires access. Users with access can use AI to search inside if `allowAIPrivateSearch` setting is enabled |
+| `assist` | Enables Lifebot AI in this node |
+| `#color#r,g,b,a` | Node background color |
+| `#markerList#<listId>` | Enables status dropdown for children |
+| `#marker#<statusId>` | Sets item status from marker list |
+
+### Markers (Status System)
+
+Markers let you track status of items (like task states). It's a pattern, not a built-in feature:
+
+1. **Create a marker list** — a node with status options as children (emoji titles)
+2. **Enable on parent** — add `#markerList#<listId>` tag
+3. **Set status** — add `#marker#<statusId>` tag to items
+
+```javascript
+// Enable default markers on a parent node
+await graph.editItem({
+    id: parentId,
+    tags: ['#markerList#0000018190aaf813-a61a6f263e6a0000']
+});
+
+// Mark item as completed (default marker)
+await graph.editItem({
+    id: taskId,
+    tags: ['#marker#0000018195a2d792-a61a6f263e6a0000']  // ☑️ Completed
+});
+```
+
+See `CLAUDE.md` for full marker documentation and default marker IDs.
+
+---
+
+## CLI Usage
+
+```bash
+# Install globally
+npm install -g @ilivemylife/graph-sdk
+
+# Login (saves token to ~/.ilivemylife/config.json)
+ilml login
+
+# Queries (read operations) - all support --json for scripting
+ilml items <nodeId>              # List node and children (short)
+ilml items <nodeId> --single     # Node only, no children
+ilml items <nodeId> --long       # Full details (all fields)
+ilml items <nodeId> --json       # JSON output (for scripting)
+ilml items <nodeId> --ids        # IDs only (for piping)
+ilml messages <nodeId> [count]   # Show messages (short)
+ilml messages <nodeId> --long    # Full message details
+ilml messages <nodeId> --json    # JSON output
+ilml itemHistory <nodeId>        # Show change history
+ilml itemHistory <nodeId> --json # JSON output
+ilml itemUsers <nodeId> --json   # Users with access
+ilml subItemCount <nodeId>       # Get children count
+ilml itemSettings <nodeId>       # Show node settings
+ilml search <nodeId> "text"      # Search messages
+ilml tree <nodeId> [depth]       # Show tree structure (truncated)
+ilml tree <nodeId> --long        # Full titles, no truncation
+
+# Item mutations
+ilml addItem <parentId> --title "Task" --desc "Description" --tags work,urgent
+ilml addItem <parentId> --ref <nodeId>  # Create link to another node
+ilml editItem <nodeId> --title "New Title" --tags updated
+ilml archiveItem <nodeId>
+ilml unarchiveItem <nodeId>
+ilml moveItem <nodeId> <fromParentId> <toParentId>
+ilml reorderChild <parentId> <from> <to>  # Reorder child (1-based positions)
+ilml setPosition <nodeId> <parentId> <pos>  # Move to position (1-based)
+
+# Messaging
+ilml send <nodeId> "message"     # Send message (no AI)
+ilml ask <nodeId> "question"     # Ask AI and wait for response
+ilml editMessage <msgId> "new content"
+ilml archiveMessage <msgId>
+
+# Management
+ilml config                      # Show configuration
+ilml me                          # Current user info
+```
+
+### Token Configuration
+
+Token is resolved in order:
+1. `.ilivemylife/config.json` in current directory (or parent directories)
+2. `.env` file with `ILML_TOKEN` in current directory
+3. `~/.ilivemylife/config.json` (global, set by `ilml login`)
+4. `ILML_TOKEN` environment variable
+
+This allows per-project tokens:
+```bash
+# Project A uses user A's token
+project-a/.ilivemylife/config.json   # via: ilml login --local
+
+# Or use .env file
+project-b/.env                        # ILML_TOKEN=xxx
+```
+
+---
+
+## MCP Server (AI Assistant Integration)
+[MCP (Model Context Protocol)](https://modelcontextprotocol.io/) allows AI assistants to interact with external tools. This SDK includes an MCP server that exposes graph operations to Claude, Cursor, Windsurf and other MCP-compatible tools.
+
+### Setup
+
+**Claude Code (quick):**
+```bash
+claude mcp add --env ILML_TOKEN=your-token ilml -- ilml-mcp
+```
+
+**Claude Code (manual)** — add to `~/.claude/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "ilml": {
+      "command": "ilml-mcp",
+      "env": { "ILML_TOKEN": "your-token" }
+    }
+  }
+}
+```
+
+**Other AI tools** — same JSON content, different config file:
+
+| AI Tool | Config Path |
+|---------|------------|
+| Claude Code | `~/.claude/settings.json` or `claude mcp add` |
+| Claude Desktop | macOS: `~/Library/Application Support/Claude/claude_desktop_config.json` |
+| | Windows: `%APPDATA%\Claude\claude_desktop_config.json` |
+| Cursor | `~/.cursor/mcp.json` |
+| Windsurf | `~/.codeium/windsurf/mcp_config.json` |
+
+Restart your AI tool after adding the config.
+
+### Available Tools
+
+**Read Operations** (no confirmation needed):
+- `graph_items` — Get node and children
+- `graph_messages` — Get messages from node
+- `graph_search_messages` — Search messages
+- `graph_item_history` — Get change history
+- `graph_item_users` — Get users with access
+- `graph_item_settings` — Get node settings
+- `graph_me` — Get current user info
+- `graph_info` — Get documentation about graph features
+
+**Write Operations** (require confirmation):
+- `graph_add_item` — Create new node
+- `graph_edit_item` — Edit node (title, description, tags)
+- `graph_archive_item` / `graph_unarchive_item` — Archive/restore
+- `graph_move_item` — Move to different parent
+- `graph_reorder_child` / `graph_set_position` — Reorder
+- `graph_add_message` — Send message
+- `graph_ask_lifebot` — Ask AI and wait for response
+
+### Example Prompts
+
+```
+"Show me items in node abc123"
+"Create a task called 'Review PR' under node xyz789"
+"What messages are in my root node?"
+"Ask Lifebot to summarize this project"
+```
+
+---
+
+## TypeScript
+
+Full type definitions included:
+
+```typescript
+import type {
+    // Data types
+    Item, Message, User, ItemSettings,
+
+    // Client types
+    GraphClient, GraphClientOptions,
+    AddItemOptions, EditItemInput, AddMessageOptions,
+
+    // Subscription change types (for type-safe comparisons)
+    MessageChangeType,  // '+1' | 'edit' | '-1'
+    ItemChangeType      // '+1' | 'edit' | '-1' | 'movedIn' | 'reorder'
+} from '@ilivemylife/graph-sdk';
+```
+
+---
+
+## Publishing New Versions
+
+```bash
+# First time: login to npm
+npm login
+
+# First publish
+npm publish --access public
+
+# Update versions:
+npm run release:patch   # 1.0.0 → 1.0.1 (bug fixes)
+npm run release:minor   # 1.0.0 → 1.1.0 (new features)
+npm run release:major   # 1.0.0 → 2.0.0 (breaking changes)
+```
+
+---
+
+## License
+
+© 2026 Ilya Sorokin. All rights reserved.
+
+This package is proprietary software. For licensing inquiries, business partnerships, or enterprise usage, please contact the author.
+
+---
+
+## Author
+
+Created by **Ilya Sorokin** — founder and developer of iLiveMyLife.
+
+- **LinkedIn:** [linkedin.com/in/ilyasorokin](https://www.linkedin.com/in/ilyasorokin/)
+- **Email:** info@ilivemylife.io
+- **App:** [https://iLiveMyLife.io](https://iLiveMyLife.io)