@ilivemylife/graph-sdk 1.0.0

package/examples/README.md

@@ -0,0 +1,143 @@
+# SDK Usage Examples
+
+Examples demonstrating how to use the iLiveMyLife Graph SDK.
+
+## Setup
+
+```bash
+# 1. Install dependencies (from project root)
+npm install
+
+# 2. Build the SDK
+npm run build
+
+# 3. Login to get your token
+node dist/cli.mjs login
+
+# 4. Run examples
+node examples/getting-started.mjs
+```
+
+Or set token manually:
+```bash
+export ILML_TOKEN="your-access-token"
+node examples/getting-started.mjs
+```
+
+## Getting Your Token
+
+**Option 1: CLI Login**
+```bash
+npx ilml login
+# Token saved automatically to ~/.ilivemylife/config.json
+```
+
+**Option 2: Browser DevTools**
+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. Find `access-token` in Request Headers and copy its value
+
+## Examples
+
+### 1. Getting Started (Start Here!)
+```bash
+node examples/getting-started.mjs
+```
+**Works without NODE_ID!** Complete walkthrough:
+- Connect with your token
+- Navigate your "My Life" tree
+- Read node fields (title, description, tags, etc.)
+- Create nodes with tags (like `private`)
+- Create child nodes
+- Edit nodes (partial updates)
+- Reorder children
+- Understand eventual consistency
+
+### 2. Messenger & Lifebot
+```bash
+node examples/messenger-basics.mjs
+```
+Working with messages and AI:
+- Read messages from a node
+- Send messages (without AI response)
+- Ask Lifebot questions
+- Ask Lifebot to create nodes
+- Ask Lifebot to create structure (nested nodes)
+
+### 3. Ask Lifebot (Simple)
+```bash
+export NODE_ID="your-node-id"
+node examples/ask-lifebot.mjs
+```
+Focused example of AI interaction with error handling.
+
+### 4. Manage Items
+```bash
+export NODE_ID="your-node-id"
+node examples/manage-items.mjs
+```
+Creating, editing, reordering, archiving items.
+
+### 5. Real-time Subscriptions
+```bash
+export NODE_ID="your-node-id"
+node examples/subscriptions.mjs
+```
+Subscribing to message and item changes in real-time.
+
+### 6. Error Handling
+```bash
+node examples/error-handling.mjs
+```
+Proper error handling patterns with typed exceptions.
+
+## Finding Your Node ID
+
+Node IDs are in the URL when viewing a node:
+```
+https://app.ilivemylife.io/item/00001191f13c5c81-ee4ae8284f820001
+                                 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+                                 This is the node ID
+```
+
+Or get your root node ID programmatically:
+```javascript
+const me = await graph.me();
+console.log(me.rootItemId);  // Your "My Life" root node ID
+```
+
+## What is Lifebot?
+
+Lifebot is the AI assistant that lives inside your iLiveMyLife knowledge graph.
+
+**What Lifebot can do:**
+- Answer questions about your data
+- Search and find information across nodes
+- Create new nodes with content
+- Organize information into structure
+- Execute actions on your behalf
+
+**How to use:**
+```javascript
+// Simple question
+const answer = await graph.askLifebot(nodeId, 'Summarize this project');
+
+// Ask to create something
+const result = await graph.askLifebot(nodeId,
+    'Create a node called "Weekly Tasks" with 3 sub-tasks inside');
+
+// Lifebot will create the node AND the children!
+```
+
+**Enable Lifebot:** Add `assist` tag to a node to enable Lifebot in that node.
+
+## Eventual Consistency
+
+When you write data (addItem, editItem, etc.):
+1. Command is accepted immediately
+2. You get confirmation (or error)
+3. Data propagates across the system
+
+**Important:** Reading immediately after write might return stale data. If you need real-time updates, use subscriptions.

package/examples/ask-lifebot.mjs

@@ -0,0 +1,43 @@
+/**
+ * Ask Lifebot Example
+ *
+ * Shows how to send a message and wait for AI response.
+ *
+ * Run: node examples/ask-lifebot.mjs
+ */
+
+import {
+    createGraphClient,
+    LifebotTimeoutError,
+    LifebotRateLimitError
+} from '@ilivemylife/graph-sdk';
+
+const graph = createGraphClient({
+    token: process.env.ILML_TOKEN,
+    // Optional: enable logging
+    logger: console
+});
+
+const nodeId = process.env.NODE_ID;
+
+try {
+    console.log('Asking Lifebot...');
+
+    const reply = await graph.askLifebot(nodeId, 'What is 2 + 2?', {
+        timeout: 30000  // 30 seconds timeout
+    });
+
+    console.log('Lifebot response:', reply.content);
+
+} catch (error) {
+    if (error instanceof LifebotTimeoutError) {
+        console.error('Lifebot did not respond in time');
+    } else if (error instanceof LifebotRateLimitError) {
+        console.error('Rate limit exceeded, try again later');
+    } else {
+        throw error;
+    }
+} finally {
+    // Free resources and close connections
+    graph.destroy();
+}

package/examples/error-handling.mjs

@@ -0,0 +1,89 @@
+/**
+ * Error Handling Example
+ *
+ * Shows how to properly handle SDK errors.
+ *
+ * Run: node examples/error-handling.mjs
+ */
+
+import {
+    createGraphClient,
+    GraphError,
+    GraphNetworkError,
+    GraphAuthError,
+    LifebotError,
+    LifebotRateLimitError,
+    LifebotTimeoutError,
+    GraphErrorCodes
+} from '@ilivemylife/graph-sdk';
+
+// Example 1: Missing token
+try {
+    const client = createGraphClient({ token: '' });
+} catch (error) {
+    if (error instanceof GraphError) {
+        console.log('Expected error - token required:', error.message);
+    }
+}
+
+// Example 2: Working with a valid client
+const graph = createGraphClient({
+    token: process.env.ILML_TOKEN
+});
+
+// Example 3: Handling API errors
+async function safeGetItems(nodeId) {
+    try {
+        return await graph.items(nodeId);
+    } catch (error) {
+        if (error instanceof GraphNetworkError) {
+            console.error('Network error - check your connection');
+            return [];
+        }
+        if (error instanceof GraphAuthError) {
+            console.error('Auth error - check your token');
+            return [];
+        }
+        throw error;  // Re-throw unknown errors
+    }
+}
+
+// Example 4: Handling Lifebot errors
+async function safeAskLifebot(nodeId, question) {
+    try {
+        return await graph.askLifebot(nodeId, question, { timeout: 30000 });
+    } catch (error) {
+        if (error instanceof LifebotTimeoutError) {
+            console.error(`Timeout after ${error.timeout}ms`);
+            return null;
+        }
+        if (error instanceof LifebotRateLimitError) {
+            console.error('Rate limited - waiting before retry');
+            await new Promise(r => setTimeout(r, 5000));
+            return safeAskLifebot(nodeId, question);  // Retry
+        }
+        if (error instanceof LifebotError) {
+            console.error('Lifebot error:', error.message);
+            return null;
+        }
+        throw error;
+    }
+}
+
+// Example 5: Using error codes
+async function handleMutationError() {
+    try {
+        await graph.addItem('invalid-node-id', { title: 'Test' });
+    } catch (error) {
+        if (error instanceof GraphError && error.code === GraphErrorCodes.MUTATION_FAILED) {
+            console.log('Mutation failed - check node ID');
+        }
+    }
+}
+
+// Run examples
+const nodeId = process.env.NODE_ID;
+if (nodeId) {
+    const items = await safeGetItems(nodeId);
+    console.log('Items:', items.length);
+}

package/examples/getting-started.mjs

@@ -0,0 +1,201 @@
+/**
+ * Getting Started - Complete Example
+ *
+ * Works with just ILML_TOKEN - no NODE_ID needed!
+ * Shows the core flow: navigate tree, create nodes, understand structure.
+ *
+ * Getting your token:
+ *   Option 1: npx ilml login (then token saved automatically)
+ *   Option 2: In browser app.ilivemylife.io → DevTools → Network tab →
+ *             click any request → Headers → find "access-token"
+ *
+ * Run:
+ *   node examples/getting-started.mjs
+ */
+
+import { createGraphClient } from '@ilivemylife/graph-sdk';
+
+// ============================================================================
+// Step 1: Create client
+// ============================================================================
+
+const graph = createGraphClient({
+    token: process.env.ILML_TOKEN
+});
+
+console.log('='.repeat(60));
+console.log('iLiveMyLife Graph SDK - Getting Started');
+console.log('='.repeat(60));
+
+// ============================================================================
+// Step 2: Get current user and root node
+// ============================================================================
+
+const me = await graph.me();
+console.log('\n[Your Account]');
+console.log('  Name:', me.displayName);
+console.log('  Email:', me.email);
+console.log('  Root Node ID:', me.rootItemId);
+
+// ============================================================================
+// Step 3: Navigate the tree - read root and children
+// ============================================================================
+
+// items() returns [node, ...children] - first element is the node itself
+const rootItems = await graph.items(me.rootItemId);
+const rootNode = rootItems[0];
+const rootChildren = rootItems.slice(1);
+
+console.log('\n[Your "My Life" (root) Node]');
+console.log('  Title:', rootNode.title);
+console.log('  Description:', rootNode.description || '(empty)');
+console.log('  Tags:', rootNode.tags?.join(', ') || '(none)');
+console.log('  Children:', rootChildren.length);
+
+// ============================================================================
+// Step 4: Iterate through children - show all fields
+// ============================================================================
+
+console.log('\n[Root Children]');
+if (rootChildren.length === 0) {
+    console.log('  (no children yet)');
+} else {
+    rootChildren.slice(0, 5).forEach((item, i) => {
+        console.log(`\n  ${i + 1}. "${item.title}"`);
+        console.log(`     ID: ${item.id}`);
+        console.log(`     Description: ${item.description || '(empty)'}`);
+        console.log(`     Tags: ${item.tags?.join(', ') || '(none)'}`);
+        console.log(`     Order: ${item.order}`);
+        console.log(`     Created: ${new Date(parseInt(item.createdAt)).toLocaleString()}`);
+        console.log(`     By: ${item.createdBy}`);
+        if (item.refId) {
+            console.log(`     → Link to: ${item.refId}`);
+        }
+    });
+    if (rootChildren.length > 5) {
+        console.log(`\n  ... and ${rootChildren.length - 5} more`);
+    }
+}
+
+// ============================================================================
+// Step 5: Go deeper - read grandchildren (2 levels)
+// ============================================================================
+
+if (rootChildren.length > 0) {
+    const firstChild = rootChildren[0];
+    const childItems = await graph.items(firstChild.id);
+    const grandchildren = childItems.slice(1);
+
+    console.log(`\n[Inside "${firstChild.title}"]`);
+    console.log('  Children:', grandchildren.length);
+    grandchildren.slice(0, 3).forEach((item, i) => {
+        console.log(`    ${i + 1}. ${item.title}`);
+    });
+}
+
+// ============================================================================
+// Step 6: Create a new node
+// ============================================================================
+
+console.log('\n[Creating New Node]');
+
+const newNode = await graph.addItem(me.rootItemId, {
+    title: 'SDK Demo',
+    description: 'This node was created via iLiveMyLife Graph SDK.\n\nIt demonstrates the `addItem()` method.',
+    tags: ['private']
+});
+
+console.log('  Created:', newNode.title);
+console.log('  ID:', newNode.id);
+console.log('  URL: https://app.ilivemylife.io/item/' + newNode.id);
+
+// ============================================================================
+// Step 7: Create child nodes inside it
+// ============================================================================
+
+console.log('\n[Creating Child Nodes]');
+
+const child1 = await graph.addItem(newNode.id, {
+    title: 'First Task',
+    description: 'This is the first task in our demo project.'
+});
+console.log('  Created:', child1.title);
+
+const child2 = await graph.addItem(newNode.id, {
+    title: 'Second Task',
+    description: 'This is the second task.'
+});
+console.log('  Created:', child2.title);
+
+const child3 = await graph.addItem(newNode.id, {
+    title: 'Third Task',
+    description: 'This is the third task.'
+});
+console.log('  Created:', child3.title);
+
+// ============================================================================
+// Note on Eventual Consistency
+// ============================================================================
+// When you call addItem/editItem, the command is accepted immediately.
+// However, propagation across the system takes a moment.
+// If you read right after write, you might get stale data.
+// But once you receive confirmation (no error), data WILL propagate eventually.
+//
+// For real-time updates, use subscriptions (see subscriptions.mjs)
+
+// ============================================================================
+// Step 8: Edit a node
+// ============================================================================
+
+console.log('\n[Editing Node]');
+// Only pass fields you want to change - omitted fields stay unchanged
+const edited = await graph.editItem({
+    id: child1.id,
+    title: 'First Task (Updated)',
+    description: 'Description updated via SDK!'
+    // tags: not passed = tags stay unchanged
+    // dueDate: not passed = dueDate stays unchanged
+});
+console.log('  Updated:', edited.title);
+
+// ============================================================================
+// Step 9: Reorder children
+// ============================================================================
+
+console.log('\n[Reordering]');
+// Move last child (position 3) to first position (position 1)
+const reordered = await graph.reorderChild(newNode.id, 3, 1);
+console.log('  Moved "' + reordered.title + '" to position 1');
+
+// Verify new order
+const afterReorder = await graph.items(newNode.id);
+console.log('  New order:', afterReorder.slice(1).map(i => i.title).join(' → '));
+
+// ============================================================================
+// Done!
+// ============================================================================
+
+console.log('\n' + '='.repeat(60));
+console.log('Done! Summary:');
+console.log('='.repeat(60));
+console.log(`
+What we did:
+  1. Connected with your token
+  2. Read your user info
+  3. Navigated the tree (root → children → grandchildren)
+  4. Created a new node with title, description, tags
+  5. Created child nodes inside it
+  6. Edited a node
+  7. Reordered children
+
+View in app: https://app.ilivemylife.io/item/${newNode.id}
+
+Next examples to try:
+  - messenger-basics.mjs  - Send messages, chat in nodes
+  - ask-lifebot.mjs       - Ask AI questions, let it create nodes
+  - subscriptions.mjs     - Real-time updates
+
+CLI commands:
+  npx ilml items ${newNode.id}
+  npx ilml tree ${newNode.id}
+`);

package/examples/manage-items.mjs

@@ -0,0 +1,78 @@
+/**
+ * Item Management Example
+ *
+ * Shows how to create, edit, and organize items.
+ *
+ * Run: node examples/manage-items.mjs
+ */
+
+import { createGraphClient } from '@ilivemylife/graph-sdk';
+
+const graph = createGraphClient({
+    token: process.env.ILML_TOKEN
+});
+
+const parentNodeId = process.env.NODE_ID;
+
+// Create a new item (all fields optional)
+const newItem = await graph.addItem(parentNodeId, {
+    title: 'My New Task',
+    description: 'This is a task created via SDK',
+    tags: ['sdk', 'example'],
+    dueDate: String(Date.now() + 7 * 24 * 60 * 60 * 1000)  // timestamp string (ms)
+});
+console.log('Created item:', newItem.id, newItem.title);
+
+// Create a reference (shortcut) to another node
+// const ref = await graph.addItem(parentNodeId, {
+//     refId: 'target-node-id',           // ID of the original node
+//     title: 'Custom Title',             // optional: override original title
+//     description: 'Custom description'  // optional: override original description
+// });
+// console.log('Created ref:', ref.id, '→', ref.refId);
+
+// Edit the item
+const editedItem = await graph.editItem({
+    id: newItem.id,
+    title: 'My Updated Task',
+    description: 'Description updated via SDK'
+});
+console.log('Updated item:', editedItem.title);
+
+// Get all items to see current order
+const items = await graph.items(parentNodeId);
+const children = items.slice(1);  // First item is the parent itself
+console.log('Children count:', children.length);
+
+// Resolve a node — if it has refId, follows it to get the original node.
+// Returns the node itself if it has no refId.
+if (children.length > 0) {
+    const firstChild = children[0];
+    const resolved = await graph.resolveRef(firstChild.id);
+    if (resolved) {
+        console.log('Resolved:', firstChild.title, firstChild.refId ? `→ ${resolved.title}` : '(not a ref)');
+    }
+}
+
+if (children.length >= 2) {
+    // Move child from last position to position 2 (1-based)
+    const lastPosition = children.length;
+    const reordered = await graph.reorderChild(parentNodeId, lastPosition, 2);
+    console.log('Reordered to position 2:', reordered.title);
+
+    // Move specific node to position 1
+    const moved = await graph.setPosition(newItem.id, parentNodeId, 1);
+    console.log('Set position to 1:', moved.title);
+}
+
+// Move item to a different parent
+// await graph.moveItem(newItem.id, parentNodeId, otherParentId);                  // to the end
+// await graph.moveItemToPosition(newItem.id, parentNodeId, otherParentId, 3);     // to position 3
+
+// Archive the item
+await graph.archiveItem(newItem.id);
+console.log('Item archived');
+
+// Unarchive if needed
+await graph.unarchiveItem(newItem.id);
+console.log('Item unarchived');