@liquidmetal-ai/raindrop 0.13.0 → 0.15.0

package/templates/handlers/bucket-event-observer.ts.hbs

@@ -0,0 +1,79 @@
+import {
+  BucketEventNotification,
+  Each,
+  Message,
+} from '@liquidmetal-ai/raindrop-framework';
+import { Env } from './raindrop.gen';
+
+/**
+ * Bucket Event Observer
+ *
+ * This observer reacts to events on the "{{bucketName}}" bucket.
+ * It processes upload, deletion, and multipart upload events.
+ *
+ * Use cases:
+ * - File processing pipelines
+ * - Automatic indexing
+ * - Thumbnail generation
+ * - Metadata extraction
+ * - Backup and sync operations
+ */
+export default class extends Each<BucketEventNotification, Env> {
+  async process(message: Message<BucketEventNotification>): Promise<void> {
+    const event = message.body;
+
+    this.env.logger.info('Bucket event received', {
+      action: event.action,
+      bucket: event.bucket,
+      key: event.object.key,
+      size: event.object.size,
+      eTag: event.object.eTag,
+    });
+
+    // Handle different event types
+    switch (event.action) {
+      case 'ObjectCreated:Put':
+        await this.handleUpload(event);
+        break;
+
+      case 'ObjectRemoved:Delete':
+        await this.handleDeletion(event);
+        break;
+
+      case 'ObjectCreated:Post':
+        await this.handleMultipartUpload(event);
+        break;
+
+      default:
+        this.env.logger.warn('Unhandled event type', { action: event.action });
+    }
+  }
+
+  private async handleUpload(event: BucketEventNotification): Promise<void> {
+    this.env.logger.info('Processing file upload', {
+      key: event.object.key,
+      size: event.object.size,
+    });
+
+    // Add your upload processing logic here
+    // Example: trigger processing, update index, send notifications
+  }
+
+  private async handleDeletion(event: BucketEventNotification): Promise<void> {
+    this.env.logger.info('Processing file deletion', {
+      key: event.object.key,
+    });
+
+    // Add your deletion logic here
+    // Example: clean up related data, update index, notify systems
+  }
+
+  private async handleMultipartUpload(event: BucketEventNotification): Promise<void> {
+    this.env.logger.info('Processing multipart upload', {
+      key: event.object.key,
+      size: event.object.size,
+    });
+
+    // Add your multipart upload logic here
+  }
+}

package/templates/handlers/http-service/index.test.ts.hbs

@@ -31,8 +31,11 @@ function createMockEnv() {
 import handler from './index.js';
 
 describe('{{serviceName}} HTTP Service', () => {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
   let service: any;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
   let env: any;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
   let ctx: any;
 
   beforeEach(() => {

package/templates/handlers/http-service/index.ts.hbs

@@ -2,12 +2,12 @@ import { Service } from '@liquidmetal-ai/raindrop-framework';
 import { Hono } from 'hono';
 import { Env } from './raindrop.gen';
 
-// Web API types that should be available in Cloudflare Workers
-// These type aliases ensure compatibility between test and runtime environments
-type Headers = globalThis.Headers;
-type Blob = globalThis.Blob;
-type FormData = globalThis.FormData;
-type ReadableStream = globalThis.ReadableStream;
+// Web API types available in Cloudflare Workers runtime:
+// Uncomment these type aliases if you need to ensure compatibility between test and runtime environments
+// type Headers = globalThis.Headers;
+// type Blob = globalThis.Blob;
+// type FormData = globalThis.FormData;
+// type ReadableStream = globalThis.ReadableStream;
 
 // Create Hono app
 const app = new Hono<{ Bindings: Env }>();
@@ -18,6 +18,10 @@ app.get('/health', (c) => {
 });
 
 // === Add Your API Routes Here ===
+//
+// IMPORTANT: The example endpoints below are used by tests.
+// DO NOT remove them - add your new endpoints alongside these examples.
+// Removing these endpoints will break the test suite.
 
 // Example: Simple GET endpoint
 app.get('/api/hello', (c) => {
@@ -46,16 +50,38 @@ app.post('/api/echo', async (c) => {
   }
 });
 
-// === Production Patterns Available ===
-// Need authentication, database, or file uploads? These are available:
+// Add your production endpoints here (keep examples above for tests):
+// app.post('/chat', async (c) => { /* your logic */ });
+// app.post('/upload', async (c) => { /* your logic */ });
+
+// === Add Production Features ===
+// IMPORTANT: Use setup commands to get working examples with correct APIs!
+//
+//   $ raindrop build features              # See all 8 available features
+//   $ raindrop build smartmemory setup     # Conversation memory → src/examples/
+//   $ raindrop build smartsql setup        # Database queries → src/examples/
+//   $ raindrop build smartbucket setup     # File storage → src/examples/
+//   $ raindrop build workos setup          # Authentication
+//   $ raindrop build stripe setup          # Payments
+//
+// Setup commands create src/examples/ with actual API usage.
+// DO NOT guess at APIs - check examples for correct methods!
+//
+// === AI Model Usage ===
+// The AI binding is automatically available via this.env.AI
+// DO NOT declare "ai" in your manifest - it's auto-provided!
 //
-// • File storage & AI search → https://docs.liquidmetal.ai/reference/smartbucket
-// • Database & natural language queries → https://docs.liquidmetal.ai/reference/smartsql
-// • AI agent memory management → https://docs.liquidmetal.ai/reference/smartmemory
-// • Background job processing → https://docs.liquidmetal.ai/reference/queue
-// • Authentication & security → https://docs.liquidmetal.ai/sdk/authentication
+// Correct usage:
+//   const result = await this.env.AI.run('openai', {
+//     model: 'gpt-4',
+//     messages: [{ role: 'user', content: 'Hello' }]
+//   });
 //
-// These production features are automatically configured when you add resources to your raindrop.manifest
+// For Llama models:
+//   const result = await this.env.AI.run('openai', {
+//     model: 'llama-3.3-70b',
+//     messages: [...]
+//   });
 
 export default class extends Service<Env> {
   async fetch(request: Request): Promise<Response> {
@@ -65,6 +91,8 @@ export default class extends Service<Env> {
     // • Rate limiting and security headers
     // • Metrics collection and health monitoring
 
-    return app.fetch(request, this.env, this.ctx);
+    // IMPORTANT: Pass this.env so Hono routes can access bindings via c.env
+    // DO NOT pass this.ctx (ExecutionContext) - Hono only accepts (request, env)
+    return app.fetch(request, this.env);
   }
 }

package/templates/handlers/queue-consumer-setup.ts.hbs

@@ -0,0 +1,45 @@
+import { Each, Message } from '@liquidmetal-ai/raindrop-framework';
+import { Env } from './raindrop.gen';
+
+/**
+ * {{queueName}} Consumer
+ *
+ * This observer processes messages from the "{{queueName}}" queue.
+ * Messages are processed asynchronously in the background.
+ *
+ * Use cases:
+ * - Background job processing
+ * - Async task execution
+ * - Event-driven workflows
+ * - Decoupling services
+ */
+export default class extends Each<MessageBody, Env> {
+  async process(message: Message<MessageBody>): Promise<void> {
+    this.env.logger.info('Processing queue message', {
+      messageId: message.id,
+      timestamp: message.timestamp,
+      body: message.body,
+    });
+
+    // Add your message processing logic here
+    // Example: handle different message types
+    const body = message.body;
+
+    if (body.task === 'example-task') {
+      await this.handleExampleTask(body);
+    }
+
+    // Message will be automatically acknowledged on successful return
+    // Throw an error to retry the message
+  }
+
+  private async handleExampleTask(body: MessageBody): Promise<void> {
+    this.env.logger.info('Handling example task', { body });
+    // Add your task logic here
+  }
+}
+
+export interface MessageBody {
+  task?: string;
+  [key: string]: any;
+}

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

@@ -1,18 +1,16 @@
 /**
  * Tests for Task 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 scheduled tasks
+ * - Tests actual task execution
+ * - Covers basic error scenarios
+ * - Easy to extend with additional tests
  */
 
 import { expect, test, describe, beforeEach, vi } from 'vitest';
 
-// Simple mock environment - add your actual bindings here
+// Simple mock environment with only what this template uses
 function createMockEnv() {
   return {
     _raindrop: {
@@ -26,10 +24,7 @@ function createMockEnv() {
       error: vi.fn(),
       warn: vi.fn(),
     },
-    // Add your environment bindings that the task uses:
-    // DATABASE: { executeQuery: vi.fn() },
-    // CACHE: { get: vi.fn(), put: vi.fn() },
-    // EXTERNAL_API: { post: vi.fn() },
+    // Add additional bindings here as you add features to your task
   };
 }
 
@@ -46,7 +41,7 @@ describe('{{taskClassName}} Task', () => {
     task = new handler(ctx, env);
   });
 
-  test('can instantiate task', () => {
+  test('task instantiates correctly', () => {
     expect(task).toBeDefined();
     expect(typeof task.handle).toBe('function');
   });
@@ -57,124 +52,47 @@ describe('{{taskClassName}} Task', () => {
     expect(env._raindrop.app.organizationId).toBe('test-org');
   });
 
-  // === ESSENTIAL PRODUCTION SAFETY TESTS ===
+  // === Essential Task Tests ===
 
-  test('handles basic scheduled events', async () => {
+  test('handles scheduled events', async () => {
     const event: any = {
       type: 'scheduled',
-      scheduledTime: new Date().toISOString(),
+      scheduledTime: Date.now(),
       cron: '0 8 * * *',
     };
 
-    // Should handle the event without throwing
-    await expect(task.handle(event)).resolves.not.toThrow();
-  });
-
-  test('handles missing event gracefully', async () => {
-    // Should handle null/undefined events without crashing
-    await expect(task.handle(null as any)).resolves.not.toThrow();
-    await expect(task.handle(undefined as any)).resolves.not.toThrow();
-  });
+    await task.handle(event);
 
-  test('handles empty event objects', async () => {
-    const event = {};
-    
-    // Should handle empty events gracefully
-    await expect(task.handle(event as any)).resolves.not.toThrow();
+    expect(env.logger.info).toHaveBeenCalledWith(
+      'Scheduled task executed',
+      expect.objectContaining({ cron: '0 8 * * *' })
+    );
   });
 
-  test('processes multiple consecutive runs', async () => {
+  test('handles errors gracefully', async () => {
     const event: any = {
       type: 'scheduled',
-      scheduledTime: new Date().toISOString(),
+      scheduledTime: Date.now(),
+      cron: '*/5 * * * *',
     };
 
-    // Should handle multiple calls without issues
-    await task.handle(event);
-    await task.handle(event);
-    await task.handle(event);
-
-    expect(true).toBe(true); // If we get here, no errors thrown
+    // Should not throw even if task logic errors
+    await expect(task.handle(event)).resolves.toBeUndefined();
   });
 
-  test('logs task execution', async () => {
+  test('processes multiple consecutive runs', async () => {
     const event: any = {
       type: 'scheduled',
-      scheduledTime: new Date().toISOString(),
+      scheduledTime: Date.now(),
+      cron: '0 * * * *',
     };
 
+    await task.handle(event);
+    await task.handle(event);
     await task.handle(event);
 
-    // Verify some logging occurred (for debugging)
-    expect(env.logger.info || env.logger.warn || env.logger.error).toHaveBeenCalled();
-  });
-
-  // === EDGE CASE GUARD RAILS ===
-
-  test('handles malformed events gracefully', async () => {
-    // Guard rail: Catches circular reference issues
-    const event: any = { type: 'test' };
-    event.self = event; // Circular reference
-
-    // Should not crash during logging or processing
-    await expect(task.handle(event)).resolves.not.toThrow();
-  });
-
-  test('handles events with special characters', async () => {
-    // Guard rail: Ensures no injection issues
-    const event: any = {
-      type: 'test',
-      data: '<script>alert("xss")</script>',
-      sqlQuery: "'; DROP TABLE users--",
-    };
-
-    await expect(task.handle(event)).resolves.not.toThrow();
-  });
-
-  test('handles events with unicode content', async () => {
-    // Guard rail: Validates UTF-8 handling
-    const event: any = {
-      type: 'test',
-      message: 'Hello 世界 🌍',
-      unicodeData: '测试数据',
-    };
-
-    await expect(task.handle(event)).resolves.not.toThrow();
+    expect(env.logger.info).toHaveBeenCalledTimes(6); // 3 executions * 2 logs each
   });
 
-  // ADD CUSTOM BUSINESS LOGIC TESTS HERE
-  // Example:
-  // test('processes business logic correctly', async () => {
-  //   const mockDb = { 
-  //     executeQuery: vi.fn().mockResolvedValue({ success: true })
-  //   };
-  //   env.DATABASE = mockDb;
-  //   
-  //   const event = {
-  //     type: 'daily_report',
-  //     reportType: 'sales'
-  //   };
-  //   
-  //   await task.handle(event);
-  //   
-  //   expect(mockDb.executeQuery).toHaveBeenCalledWith(
-  //     expect.stringContaining('sales_report')
-  //   );
-  // });
-  // 
-  // test('handles external API calls', async () => {
-  //   const mockApi = { 
-  //     post: vi.fn().mockResolvedValue({ status: 'ok' })
-  //   };
-  //   env.EXTERNAL_API = mockApi;
-  //   
-  //   const event = {
-  //     type: 'sync_data',
-  //     endpoint: '/webhook'
-  //   };
-  //   
-  //   await task.handle(event);
-  //   
-  //   expect(mockApi.post).toHaveBeenCalled();
-  // });
-});
+  // === Add Your Custom Tests Here ===
+});

package/templates/handlers/task/index.ts.hbs

@@ -4,72 +4,33 @@ import { Env } from './raindrop.gen';
 export default class extends Task<Env> {
   async handle(event: Event): Promise<void> {
     try {
-      // Basic event validation - Event interface has specific fields
-      if (!event || typeof event !== 'object') {
-        this.env.logger.warn('Invalid event received', { eventType: 'invalid' });
-        return;
-      }
-
-      // Extract event type safely - Event only has 'scheduled' type
-      const eventType = event.type || 'scheduled';
-      const eventData = event; // Event object contains cron, type, scheduledTime
-      
-      this.env.logger.info('Task executed', { 
-        eventType,
-        scheduledTime: event.scheduledTime
+      this.env.logger.info('Scheduled task executed', {
+        cron: event.cron,
+        scheduledTime: event.scheduledTime,
       });
 
-      // Handle different event types (currently only 'scheduled' exists)
-      if (eventType === 'scheduled') {
-        await this.handleScheduledTask(eventData);
-      } else {
-        // For future event types
-        this.env.logger.warn('Unknown event type', { eventType });
-      }
+      // === Add Your Task Logic Here ===
+
+      // Example: Process scheduled data cleanup, reports, etc.
+      await this.processScheduledTask(event);
+
     } catch (error) {
       const errorMessage = error instanceof Error ? error.message : 'Unknown error';
-      this.env.logger.error('Task execution failed', { 
+      this.env.logger.error('Task execution failed', {
         error: errorMessage,
-        eventType: event?.type || 'unknown'
+        cron: event.cron,
       });
-      
-      // Don't throw - tasks should handle errors gracefully
-      return;
     }
   }
 
-  private async handleScheduledTask(data: any): Promise<void> {
-    this.env.logger.info('Processing scheduled task', { cron: data.cron });
-    
-    // Note: waitUntil background operations
-    // This depends on execution context - commented out for now
-    // if ('waitUntil' in this.env) {
-    //   this.env.waitUntil(Promise.resolve('Background operation'));
-    // }
-  }
-
-  private async handleManualTask(data: any): Promise<void> {
-    this.env.logger.info('Processing manual task', { data });
-  }
-
-  // === Integration Examples ===
+  private async processScheduledTask(event: Event): Promise<void> {
+    this.env.logger.info('Processing scheduled task', { cron: event.cron });
 
-  // Example: Call an actor (if you have actors in manifest)
-  private async callActor(actorName: string, methodName: string, data: any): Promise<any> {
-    return { error: 'Actor integration not implemented in this template' };
-  }
-
-  // Example: Use storage - update bucket binding name to match your manifest
-  private async saveResult(key: string, data: any): Promise<void> {
-    try {
-      // Example: Use FILES binding (if you have bucket "files" in manifest)
-      // const bucket = this.env.FILES;
-      // Replace with your actual bucket binding name from raindrop.gen.ts
-      throw new Error('Bucket binding not configured - update this method to use your bucket binding');
-    } catch (error) {
-      const errorMessage = error instanceof Error ? error.message : 'Unknown error';
-      this.env.logger.error('Failed to save result', { error: errorMessage, key });
-      throw error;
-    }
+    // Add your scheduled task logic here
+    // Examples:
+    // - Generate daily reports
+    // - Clean up old data
+    // - Send scheduled notifications
+    // - Aggregate metrics
   }
-}
+}

package/templates/init/RAINDROP.md.hbs

@@ -23,7 +23,18 @@ A Raindrop application built with Hono.js and modern web technologies.
    raindrop build generate
    ```
 
-3. **Deploy to Raindrop**
+3. **Discover available features** (recommended for new apps)
+   ```bash
+   raindrop build features
+   ```
+
+4. **Add features you need** (example)
+   ```bash
+   raindrop build smartmemory setup
+   raindrop build smartsql setup
+   ```
+
+5. **Deploy to Raindrop**
    ```bash
    raindrop build deploy --start
    ```
@@ -33,6 +44,53 @@ A Raindrop application built with Hono.js and modern web technologies.
    npm run start
    ```
 
+## Best Practices for Using Examples
+
+When adding features to your app, follow this workflow to avoid issues:
+
+### ✅ Recommended Workflow
+
+1. **Run setup commands to get examples**
+   ```bash
+   raindrop build smartmemory setup
+   raindrop build smartsql setup
+   ```
+
+2. **Test that examples compile**
+   ```bash
+   npm run build
+   ```
+   If examples don't compile, check that you ran `raindrop build generate` first.
+
+3. **Study the examples for correct API usage**
+   ```bash
+   cat src/examples/smartmemory-minimal.ts
+   ```
+   Examples show actual available methods - do not guess at APIs!
+
+4. **Adapt examples for your use case**
+   Copy patterns from examples into your handlers. Don't rewrite from scratch.
+
+### ❌ Common Mistakes to Avoid
+
+- **Don't remove template example endpoints** - The `/api/hello`, `/api/echo` endpoints are used by tests. Add your endpoints alongside them, don't replace them.
+- **Don't manually edit manifest without running generate** - You'll be missing TypeScript types
+- **Don't guess at API methods** - Check examples for actual available methods
+  - SmartBucket has: `put()`, `get()`, `list()`, `delete()`, `head()` (no `search()`!)
+  - SmartMemory has: `startWorkingMemorySession()`, `getWorkingMemorySession(sessionId)`
+  - SmartSQL has: `executeQuery({ sqlQuery })`, `executeQuery({ textQuery })`
+- **Don't ignore binding names** - Use the exact names from your manifest in examples
+- **Don't skip `npm run build`** - Compile errors catch API mistakes early
+- **Don't declare `ai` in manifest** - AI is auto-available via `this.env.AI`
+
+### 🔍 Troubleshooting
+
+If you see errors about missing types or methods:
+1. Run `raindrop build generate` to update types
+2. Check `src/examples/` for correct API patterns
+3. Verify binding names match between manifest and code
+4. Run `npm run build` to catch TypeScript errors
+
 ## Raindrop Commands
 
 ### Essential Commands
@@ -41,6 +99,7 @@ A Raindrop application built with Hono.js and modern web technologies.
 |---------|-------------|-------------|
 | `raindrop build validate` | Validate your manifest | After changing `raindrop.manifest` |
 | `raindrop build generate` | Generate TypeScript types and handler scaffolding | After changing `raindrop.manifest` |
+| `raindrop build features` | List available features and integrations | When starting or adding functionality |
 | `raindrop build deploy --start` | Build, upload and start your application | When ready to deploy |
 | `raindrop build stop` | Stop your running application | To stop services |
 | `raindrop build status` | Check deployment status | To see current state |
@@ -141,6 +200,40 @@ import { corsAllowAll } from '@liquidmetal-ai/raindrop-framework/core/cors';
 export const cors = corsAllowAll;
 ```
 
+## Available Features
+
+Raindrop provides powerful features you can add to your application. Discover them with:
+
+```bash
+raindrop build features
+```
+
+### Popular Features
+
+| Feature | Description | Setup Command |
+|---------|-------------|---------------|
+| **SmartMemory** | AI conversation memory management | `raindrop build smartmemory setup` |
+| **SmartSQL** | PostgreSQL with natural language queries | `raindrop build smartsql setup` |
+| **SmartBucket** | File storage with AI-powered search | `raindrop build smartbucket setup` |
+| **Stateful Actor** | Durable objects with state management | `raindrop build actor setup` |
+| **Queue Consumer** | Background message processing | `raindrop build queue setup` |
+| **WorkOS Auth** | Authentication with WorkOS | `raindrop build workos setup` |
+| **Stripe Payments** | Payment processing with Stripe | `raindrop build stripe setup` |
+
+### Example: Adding SmartMemory
+
+```bash
+# 1. Set up SmartMemory in your app
+raindrop build smartmemory setup
+
+# 2. Generate updated types
+raindrop build generate
+
+# 3. Use in your handler
+const { workingMemory } = await this.env.MEMORY.startWorkingMemorySession();
+await workingMemory.putMemory({ content: 'Hello', agent: 'user' });
+```
+
 ## Manifest Configuration
 
 Your `raindrop.manifest` defines all resources and modules:
@@ -194,6 +287,9 @@ Your handlers are generated in `src/handlers/` with comprehensive examples:
 # After raindrop init
 npm install
 raindrop build generate
+
+# Optional but recommended: explore features
+raindrop build features
 ```
 
 ### 2. Development Cycle