@liquidmetal-ai/raindrop 0.13.0 → 0.15.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@liquidmetal-ai/raindrop",
   "description": "CLI for the Raindrop platform",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "author": "bosgood",
   "bin": {
     "raindrop": "./bin/run.js"
@@ -35,8 +35,8 @@
     "typescript": "^5",
     "zod": "^3.23.8",
     "zx": "^8.1.9",
-    "@liquidmetal-ai/drizzle": "0.13.0",
-    "@liquidmetal-ai/raindrop-framework": "0.13.0"
+    "@liquidmetal-ai/drizzle": "0.15.0",
+    "@liquidmetal-ai/raindrop-framework": "0.15.0"
   },
   "devDependencies": {
     "@changesets/cli": "^2.27.9",

package/templates/examples/smartbucket-minimal.ts.hbs

@@ -0,0 +1,87 @@
+import { Service } from '@liquidmetal-ai/raindrop-framework';
+import { Env } from '../{{handlerName}}/raindrop.gen';
+
+/**
+ * SmartBucket Minimal Example
+ *
+ * IMPORTANT: SmartBucket provides basic file storage operations.
+ * Available methods: put(), get(), delete(), list(), head()
+ * NOT available: search(), query(), find() - these do not exist!
+ *
+ * This example shows how to use SmartBucket for file storage:
+ * - Upload files with put()
+ * - Download files with get()
+ * - Get file metadata with head()
+ * - List files with list()
+ */
+export default class SmartBucketExample extends Service<Env> {
+  async fetch(request: Request): Promise<Response> {
+    const url = new URL(request.url);
+    const path = url.pathname;
+
+    try {
+      // POST /upload - Upload a file
+      if (path === '/upload' && request.method === 'POST') {
+        const formData = await request.formData();
+        const file = formData.get('file') as File;
+        if (!file) {
+          return new Response('No file provided', { status: 400 });
+        }
+
+        const result = await this.env.{{bindingName}}.put(file.name, file.stream(), {
+          httpMetadata: {
+            contentType: file.type,
+          },
+        });
+
+        return new Response(JSON.stringify({
+          message: 'File uploaded successfully',
+          key: result.key,
+          size: result.size,
+        }), {
+          headers: { 'Content-Type': 'application/json' },
+        });
+      }
+
+      // GET /files/:key - Download a file
+      if (path.startsWith('/files/') && request.method === 'GET') {
+        const key = path.split('/files/')[1] || '';
+        const object = await this.env.{{bindingName}}.get(key);
+
+        if (!object) {
+          return new Response('File not found', { status: 404 });
+        }
+
+        return new Response(object.body, {
+          headers: {
+            'Content-Type': object.httpMetadata?.contentType || 'application/octet-stream',
+          },
+        });
+      }
+
+      // GET /list - List all files
+      if (path === '/list' && request.method === 'GET') {
+        const objects = await this.env.{{bindingName}}.list();
+
+        return new Response(JSON.stringify({
+          files: objects.objects.map(obj => ({
+            key: obj.key,
+            size: obj.size,
+            uploaded: obj.uploaded,
+          })),
+        }), {
+          headers: { 'Content-Type': 'application/json' },
+        });
+      }
+
+      return new Response('Not found', { status: 404 });
+    } catch (error) {
+      return new Response(JSON.stringify({
+        error: error instanceof Error ? error.message : 'Unknown error',
+      }), {
+        status: 500,
+        headers: { 'Content-Type': 'application/json' },
+      });
+    }
+  }
+}

package/templates/examples/smartmemory-minimal.ts.hbs

@@ -0,0 +1,82 @@
+import { Service } from '@liquidmetal-ai/raindrop-framework';
+import { Env } from '../{{handlerName}}/raindrop.gen';
+
+/**
+ * SmartMemory Minimal Example
+ *
+ * IMPORTANT: Session Management Pattern
+ * - NEW session: startWorkingMemorySession() → returns {sessionId, workingMemory}
+ * - EXISTING session: getWorkingMemorySession(sessionId) → returns workingMemory
+ *
+ * Always use the sessionId returned from startWorkingMemorySession().
+ * To continue a conversation, use getWorkingMemorySession(existingSessionId).
+ *
+ * This example shows how to use SmartMemory for conversation management:
+ * - Start a memory session
+ * - Store conversation messages
+ * - Retrieve conversation history
+ * - Search and summarize memories
+ */
+export default class SmartMemoryExample extends Service<Env> {
+  async fetch(_request: Request): Promise<Response> {
+    try {
+      // Start a new memory session
+      const { sessionId, workingMemory } =
+        await this.env.{{bindingName}}.startWorkingMemorySession();
+
+      // Store conversation messages
+      await workingMemory.putMemory({
+        content: 'User: Hello! I need help with my project.',
+        key: 'message_1',
+        timeline: 'conversation',
+        agent: 'user',
+      });
+
+      await workingMemory.putMemory({
+        content: 'Assistant: I would be happy to help! What kind of project are you working on?',
+        key: 'message_2',
+        timeline: 'conversation',
+        agent: 'assistant',
+      });
+
+      await workingMemory.putMemory({
+        content: 'User: It is a web application using TypeScript.',
+        key: 'message_3',
+        timeline: 'conversation',
+        agent: 'user',
+      });
+
+      // Get recent conversation history
+      const recentMemories = await workingMemory.getMemory({
+        nMostRecent: 10,
+      });
+
+      // Search memories
+      const searchResults = await workingMemory.searchMemory({
+        terms: 'project TypeScript',
+        nMostRecent: 5,
+      });
+
+      // Summarize conversation
+      const summary = recentMemories
+        ? await workingMemory.summarizeMemory(recentMemories)
+        : null;
+
+      return new Response(JSON.stringify({
+        sessionId,
+        recentMemories,
+        searchResults,
+        summary,
+      }, null, 2), {
+        headers: { 'Content-Type': 'application/json' },
+      });
+    } catch (error) {
+      return new Response(JSON.stringify({
+        error: error instanceof Error ? error.message : 'Unknown error',
+      }), {
+        status: 500,
+        headers: { 'Content-Type': 'application/json' },
+      });
+    }
+  }
+}

package/templates/examples/smartsql-minimal.ts.hbs

@@ -0,0 +1,69 @@
+import { Service } from '@liquidmetal-ai/raindrop-framework';
+import { Env } from '../{{handlerName}}/raindrop.gen';
+
+/**
+ * SmartSQL Minimal Example
+ *
+ * IMPORTANT: SmartSQL API Methods
+ * - executeQuery({ sqlQuery, format }) - Run direct SQL
+ * - executeQuery({ textQuery, format }) - Natural language to SQL
+ * - getMetadata(tableName?) - Get database schema info
+ * - updateMetadata(tables, mode?) - Update schema metadata
+ * - getPiiData(tableName, recordId?) - Get PII detection results
+ *
+ * This example shows how to use SmartSQL for database operations:
+ * - Execute direct SQL queries
+ * - Use natural language queries
+ * - Get and update database metadata
+ */
+export default class SmartSqlExample extends Service<Env> {
+  async fetch(_request: Request): Promise<Response> {
+    try {
+      // Create a table
+      await this.env.{{bindingName}}.executeQuery({
+        sqlQuery: `
+          CREATE TABLE IF NOT EXISTS users (
+            id INTEGER PRIMARY KEY,
+            name TEXT NOT NULL,
+            email TEXT UNIQUE NOT NULL
+          )
+        `,
+      });
+
+      // Insert data
+      await this.env.{{bindingName}}.executeQuery({
+        sqlQuery: "INSERT OR IGNORE INTO users (id, name, email) VALUES (1, 'Alice', 'alice@example.com')",
+      });
+
+      // Query with SQL
+      const sqlResult = await this.env.{{bindingName}}.executeQuery({
+        sqlQuery: 'SELECT * FROM users',
+        format: 'json',
+      });
+
+      // Query with natural language
+      const nlResult = await this.env.{{bindingName}}.executeQuery({
+        textQuery: 'Show all users',
+        format: 'json',
+      });
+
+      // Get database metadata
+      const metadata = await this.env.{{bindingName}}.getMetadata('users');
+
+      return new Response(JSON.stringify({
+        sqlResult,
+        nlResult,
+        metadata,
+      }, null, 2), {
+        headers: { 'Content-Type': 'application/json' },
+      });
+    } catch (error) {
+      return new Response(JSON.stringify({
+        error: error instanceof Error ? error.message : 'Unknown error',
+      }), {
+        status: 500,
+        headers: { 'Content-Type': 'application/json' },
+      });
+    }
+  }
+}

package/templates/handlers/actor/index.test.ts.hbs

@@ -1,21 +1,19 @@
 /**
  * Tests for Actor Handler
- * 
- * BALANCED TESTING PATTERN:
- * - Simple setup (2 minutes) 
- * - Essential production safety (5 critical tests)
- * - No complex mock factories
- * - Tests actual business logic, not just "doesn't crash"
- * 
- * For 95% of cases, this template provides adequate safety net.
+ *
+ * FOCUSED TESTING APPROACH:
+ * - Simple, essential tests for actor state management
+ * - Tests actual methods, not just instantiation
+ * - Covers basic error scenarios
+ * - Easy to extend with additional tests
  */
 
 import { expect, test, describe, beforeEach, vi } from 'vitest';
 
-// Simple mock state - no complex implementations
+// Simple mock state - stores data in memory
 function createMockActorState(id: string = 'test-actor') {
   const data = new Map<string, unknown>();
-  
+
   return {
     id,
     storage: {
@@ -33,7 +31,7 @@ function createMockActorState(id: string = 'test-actor') {
   };
 }
 
-// Simple mock environment - add your actual bindings here
+// Simple mock environment with only what this template uses
 function createMockEnv() {
   return {
     _raindrop: {
@@ -47,10 +45,7 @@ function createMockEnv() {
       error: vi.fn(),
       warn: vi.fn(),
     },
-    // Add your environment bindings that the actor uses:
-    // DATABASE: { executeQuery: vi.fn() },
-    // CACHE: { get: vi.fn(), put: vi.fn() },
-    // BUCKET: { get: vi.fn(), put: vi.fn() },
+    // Add additional bindings here as you add features to your actor
   };
 }
 
@@ -68,90 +63,58 @@ describe('{{actorClassName}}', () => {
     await actor.initialize();
   });
 
-  test('can instantiate actor', () => {
+  test('actor instantiates correctly', () => {
     expect(actor).toBeDefined();
-    expect(typeof actor.incrementCounter).toBe('function');
-    expect(typeof actor.processMessage).toBe('function');
+    expect(typeof actor.increment).toBe('function');
+    expect(typeof actor.getCount).toBe('function');
   });
 
   test('initializes with default state', async () => {
-    const stateData = await actor.getState();
-    expect(stateData).toBeDefined();
-    expect(stateData!.count).toBe(0);
-    expect(stateData!.messages).toEqual([]);
-    expect(stateData!.lastUpdated).toBeDefined();
+    const count = await actor.getCount();
+    expect(count).toBe(0);
   });
 
-  // === ESSENTIAL PRODUCTION SAFETY TESTS ===
-
-  test('manages state correctly', async () => {
-    await actor.incrementCounter();
-    const count = await actor.getCounter();
-    expect(count).toBe(1);
-    
-    const storedData = await actor.getState();
-    expect(storedData!.count).toBe(1);
+  test('has access to environment bindings', () => {
+    expect(env.logger).toBeDefined();
+    expect(env._raindrop).toBeDefined();
+    expect(env._raindrop.app.organizationId).toBe('test-org');
   });
 
-  test('processes messages without crashing', async () => {
-    const result = await actor.processMessage('test message');
-    expect(result).toBeDefined();
-    expect(result.content).toBe('test message');
-    expect(result.id).toBeDefined();
-    expect(result.timestamp).toBeDefined();
-  });
+  // === Essential Actor Tests ===
 
-  test('handles storage operations', async () => {
-    // Mock the actor's save/load methods if they exist
-    const testData = { test: 'data' };
-    
-    // Test that storage calls don't crash
-    expect(() => actor.saveToBucket && actor.saveToBucket('test-key', testData)).not.toThrow();
-    expect(() => actor.loadFromBucket && actor.loadFromBucket('test-key')).not.toThrow();
+  test('increments counter correctly', async () => {
+    const firstCount = await actor.increment();
+    expect(firstCount).toBe(1);
+
+    const secondCount = await actor.increment();
+    expect(secondCount).toBe(2);
+
+    const retrievedCount = await actor.getCount();
+    expect(retrievedCount).toBe(2);
   });
 
-  test('handles cache operations', async () => {
-    // Test cache operations if they exist
-    const testData = { value: 42 };
-    
-    expect(() => actor.cacheResult && actor.cacheResult('test-key', testData)).not.toThrow();
-    expect(() => actor.getCachedResult && actor.getCachedResult('test-key')).not.toThrow();
+  test('stores and retrieves data correctly', async () => {
+    await actor.updateData('testKey', 'testValue');
+    const value = await actor.getData('testKey');
+    expect(value).toBe('testValue');
   });
 
-  test('can access environment bindings', () => {
-    expect(env.logger).toBeDefined();
-    expect(env._raindrop).toBeDefined();
-    expect(env._raindrop.app.organizationId).toBe('test-org');
+  test('handles complex data structures', async () => {
+    const complexData = {
+      nested: { value: 123 },
+      array: [1, 2, 3],
+      text: 'test',
+    };
+
+    await actor.updateData('complex', complexData);
+    const retrieved = await actor.getData('complex');
+    expect(retrieved).toEqual(complexData);
   });
 
-  test('handles edge cases gracefully', async () => {
-    // Test null/undefined inputs
-    await expect(actor.processMessage(null as any)).resolves.toBeDefined();
-    await expect(actor.processMessage(undefined as any)).resolves.toBeDefined();
-    
-    // Test special characters
-    const specialMessage = '<script>alert("xss")</script>';
-    const result = await actor.processMessage(specialMessage);
-    expect(result.content).toBe(specialMessage);
-    
-    // Test unicode
-    const unicodeMessage = 'Hello 世界 🌍';
-    const unicodeResult = await actor.processMessage(unicodeMessage);
-    expect(unicodeResult.content).toBe(unicodeMessage);
+  test('returns undefined for nonexistent keys', async () => {
+    const value = await actor.getData('nonexistent');
+    expect(value).toBeUndefined();
   });
 
-  // ADD CUSTOM BUSINESS LOGIC TESTS HERE
-  // Example:
-  // test('increments counter correctly', async () => {
-  //   await actor.incrementCounter();
-  //   await actor.incrementCounter();
-  //   const count = await actor.getCounter();
-  //   expect(count).toBe(2);
-  // });
-  // 
-  // test('handles alarms correctly', async () => {
-  //   await actor.schedulePeriodicTask('test-task', 60);
-  //   const alarm = await state.storage.getAlarm();
-  //   expect(alarm).toBeGreaterThan(Date.now());
-  // });
-});
+  // === Add Your Custom Tests Here ===
+});