openkbs 0.0.66 → 0.0.70

package/templates/.claude/skills/openkbs/patterns/public-api-item-proxy.md

@@ -0,0 +1,254 @@
+# Public API Item Proxy Pattern
+
+Complete working code for creating items via public API with geolocation capture.
+
+## Concept
+
+Accept external requests to create items with:
+- Client geolocation from CloudFront headers
+- IP address capture
+- Automatic encryption of sensitive fields
+- Item type validation
+
+## onPublicAPIRequest.js
+
+```javascript
+export const handler = async ({ payload, headers }) => {
+    const { item, attributes, itemType, action } = payload;
+
+    if (action === 'createItem') {
+        const enrichedItem = {};
+
+        // Capture geolocation from CloudFront headers
+        enrichedItem.country = openkbs.clientHeaders['cloudfront-viewer-country-name'];
+        enrichedItem.countryCode = openkbs.clientHeaders['cloudfront-viewer-country'];
+        enrichedItem.city = openkbs.clientHeaders['cloudfront-viewer-city'];
+        enrichedItem.ip = openkbs.clientHeaders['x-forwarded-for'];
+
+        // Add timestamp
+        enrichedItem.createdAt = new Date().toISOString();
+
+        // Process attributes with encryption
+        for (const attribute of attributes) {
+            const { attrName, encrypted } = attribute;
+
+            if (item[attrName] !== undefined) {
+                if (encrypted) {
+                    enrichedItem[attrName] = await openkbs.encrypt(item[attrName]);
+                } else {
+                    enrichedItem[attrName] = item[attrName];
+                }
+            }
+        }
+
+        // Create the item
+        return await openkbs.items({
+            action,
+            itemType,
+            attributes,
+            item: enrichedItem
+        });
+    }
+
+    // Handle other actions
+    if (action === 'getItem' || action === 'fetchItems') {
+        return await openkbs.items(payload);
+    }
+
+    return { error: 'Action not allowed', action };
+};
+
+module.exports = { handler };
+```
+
+## Extended Version with Validation
+
+```javascript
+export const handler = async ({ payload, headers, queryStringParameters }) => {
+    const { item, attributes, itemType, action } = payload;
+
+    // Whitelist allowed item types
+    const ALLOWED_TYPES = ['lead', 'contact', 'feedback'];
+
+    if (!ALLOWED_TYPES.includes(itemType)) {
+        return {
+            statusCode: 403,
+            body: { error: 'Item type not allowed' }
+        };
+    }
+
+    // Rate limiting check (simple example)
+    const ip = openkbs.clientHeaders['x-forwarded-for'];
+    const rateLimitKey = `ratelimit_${ip}_${itemType}`;
+
+    try {
+        const rateLimit = await openkbs.getItem(rateLimitKey);
+        const count = rateLimit?.item?.body?.count || 0;
+        const lastReset = rateLimit?.item?.body?.lastReset;
+
+        // Reset counter every hour
+        const hourAgo = Date.now() - 3600000;
+        if (lastReset && new Date(lastReset).getTime() > hourAgo && count >= 100) {
+            return {
+                statusCode: 429,
+                body: { error: 'Rate limit exceeded', retryAfter: 3600 }
+            };
+        }
+    } catch (e) {
+        // No rate limit record yet
+    }
+
+    if (action === 'createItem') {
+        const enrichedItem = {
+            // Geolocation
+            country: openkbs.clientHeaders['cloudfront-viewer-country-name'],
+            countryCode: openkbs.clientHeaders['cloudfront-viewer-country'],
+            region: openkbs.clientHeaders['cloudfront-viewer-country-region-name'],
+            city: openkbs.clientHeaders['cloudfront-viewer-city'],
+            ip: ip,
+
+            // User agent
+            userAgent: headers['user-agent'],
+
+            // Timestamps
+            createdAt: new Date().toISOString(),
+
+            // Source tracking
+            source: queryStringParameters?.source || 'api',
+            referer: headers['referer']
+        };
+
+        // Process and encrypt fields
+        for (const attribute of attributes) {
+            const { attrName, encrypted } = attribute;
+
+            if (item[attrName] !== undefined) {
+                // Validate required fields
+                if (attribute.required && !item[attrName]) {
+                    return {
+                        statusCode: 400,
+                        body: { error: `Missing required field: ${attrName}` }
+                    };
+                }
+
+                if (encrypted) {
+                    enrichedItem[attrName] = await openkbs.encrypt(item[attrName]);
+                } else {
+                    enrichedItem[attrName] = item[attrName];
+                }
+            }
+        }
+
+        // Create the item
+        const result = await openkbs.items({
+            action,
+            itemType,
+            attributes,
+            item: enrichedItem
+        });
+
+        // Update rate limit counter
+        try {
+            await openkbs.createItem({
+                itemType: 'ratelimit',
+                itemId: rateLimitKey,
+                body: {
+                    count: 1,
+                    lastReset: new Date().toISOString()
+                }
+            });
+        } catch (e) {
+            // Update existing
+            const existing = await openkbs.getItem(rateLimitKey);
+            await openkbs.updateItem({
+                itemType: 'ratelimit',
+                itemId: rateLimitKey,
+                body: {
+                    count: (existing?.item?.body?.count || 0) + 1,
+                    lastReset: existing?.item?.body?.lastReset || new Date().toISOString()
+                }
+            });
+        }
+
+        return result;
+    }
+
+    return { error: 'Action not supported' };
+};
+```
+
+## Frontend Usage
+
+```javascript
+// From website form
+async function submitLead(formData) {
+    const response = await fetch(
+        `https://chat.openkbs.com/publicAPIRequest?kbId=YOUR_KB_ID`,
+        {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+                action: 'createItem',
+                itemType: 'lead',
+                attributes: [
+                    { attrName: 'itemId', attrType: 'itemId', encrypted: false },
+                    { attrName: 'body', attrType: 'body', encrypted: true }
+                ],
+                item: {
+                    itemId: `lead_${Date.now()}`,
+                    body: JSON.stringify({
+                        name: formData.name,
+                        email: formData.email,
+                        message: formData.message
+                    })
+                }
+            })
+        }
+    );
+
+    return response.json();
+}
+```
+
+## settings.json - Item Type Configuration
+
+```json
+{
+  "itemTypes": {
+    "lead": {
+      "attributes": [
+        { "attrName": "itemId", "attrType": "itemId", "encrypted": false },
+        { "attrName": "body", "attrType": "body", "encrypted": true }
+      ]
+    }
+  },
+  "options": {
+    "priorityItems": [
+      { "limit": 100, "prefix": "lead" }
+    ]
+  }
+}
+```
+
+## Available CloudFront Headers
+
+```javascript
+openkbs.clientHeaders['cloudfront-viewer-country']       // "US"
+openkbs.clientHeaders['cloudfront-viewer-country-name']  // "United States"
+openkbs.clientHeaders['cloudfront-viewer-country-region'] // "CA"
+openkbs.clientHeaders['cloudfront-viewer-country-region-name'] // "California"
+openkbs.clientHeaders['cloudfront-viewer-city']          // "Los Angeles"
+openkbs.clientHeaders['cloudfront-viewer-latitude']      // "34.05"
+openkbs.clientHeaders['cloudfront-viewer-longitude']     // "-118.24"
+openkbs.clientHeaders['cloudfront-viewer-time-zone']     // "America/Los_Angeles"
+openkbs.clientHeaders['x-forwarded-for']                 // "1.2.3.4"
+```
+
+## Key Points
+
+1. **Geolocation from CloudFront** - Free, no external API needed
+2. **Encryption for sensitive data** - Use `openkbs.encrypt()`
+3. **Item type whitelisting** - Don't allow arbitrary types
+4. **Rate limiting** - Prevent abuse
+5. **Source tracking** - Query params for attribution
+6. **Timestamp enrichment** - Add createdAt automatically

package/templates/.claude/skills/openkbs/patterns/scheduled-tasks.md

@@ -0,0 +1,157 @@
+# Scheduled Tasks Pattern
+
+Complete working code for creating, listing, and deleting scheduled tasks.
+
+## actions.js
+
+```javascript
+// Create scheduled task
+[/<scheduleTask>([\s\S]*?)<\/scheduleTask>/s, async (match) => {
+    try {
+        const data = JSON.parse(match[1].trim());
+
+        let scheduledTime;
+
+        if (data.time) {
+            // Parse specific ISO time
+            let isoTimeStr = data.time.replace(' ', 'T');
+            if (!isoTimeStr.includes('Z') && !isoTimeStr.includes('+')) {
+                isoTimeStr += 'Z';
+            }
+            scheduledTime = new Date(isoTimeStr).getTime();
+        } else if (data.delay) {
+            // Parse relative delay: "30" (minutes), "2h" (hours), "1d" (days)
+            let delayMs = 0;
+            const delayStr = String(data.delay);
+            if (delayStr.endsWith('h')) {
+                delayMs = parseFloat(delayStr) * 60 * 60 * 1000;
+            } else if (delayStr.endsWith('d')) {
+                delayMs = parseFloat(delayStr) * 24 * 60 * 60 * 1000;
+            } else {
+                delayMs = parseFloat(delayStr) * 60 * 1000; // default minutes
+            }
+            scheduledTime = Date.now() + delayMs;
+        } else {
+            // Default: 1 hour from now
+            scheduledTime = Date.now() + (60 * 60 * 1000);
+        }
+
+        // Round to nearest minute (required by scheduler)
+        scheduledTime = Math.floor(scheduledTime / 60000) * 60000;
+
+        const response = await openkbs.kb({
+            action: 'createScheduledTask',
+            scheduledTime: scheduledTime,
+            taskPayload: {
+                message: `[SCHEDULED_TASK] ${data.message}`,
+                source: 'agent_scheduled',
+                createdAt: Date.now()
+            },
+            description: data.message.substring(0, 100)
+        });
+
+        return {
+            type: 'TASK_SCHEDULED',
+            data: {
+                scheduledTime: new Date(scheduledTime).toISOString(),
+                taskId: response.taskId,
+                message: data.message
+            },
+            ...meta
+        };
+    } catch (e) {
+        return { error: e.message || 'Failed to schedule task', ...meta };
+    }
+}],
+
+// List scheduled tasks
+[/<getScheduledTasks\/>/s, async () => {
+    try {
+        const response = await openkbs.kb({ action: 'getScheduledTasks' });
+
+        return {
+            type: 'SCHEDULED_TASKS_LIST',
+            data: response,
+            ...meta
+        };
+    } catch (e) {
+        return { error: e.message || 'Failed to get scheduled tasks', ...meta };
+    }
+}],
+
+// Delete scheduled task
+[/<deleteScheduledTask>([\s\S]*?)<\/deleteScheduledTask>/s, async (match) => {
+    try {
+        const data = JSON.parse(match[1].trim());
+
+        await openkbs.kb({
+            action: 'deleteScheduledTask',
+            timestamp: data.timestamp
+        });
+
+        return {
+            type: 'TASK_DELETED',
+            data: {
+                deletedTimestamp: data.timestamp,
+                message: 'Task deleted successfully'
+            },
+            ...meta
+        };
+    } catch (e) {
+        return { error: e.message || 'Failed to delete task', ...meta };
+    }
+}]
+```
+
+## onCronjob.js - Handle Scheduled Task Execution
+
+```javascript
+export const handler = async (event) => {
+    // Scheduled task payload is in event.payload
+    const taskPayload = event.payload;
+
+    if (taskPayload?.message?.includes('[SCHEDULED_TASK]')) {
+        // Create a new chat with the scheduled message
+        await openkbs.chats({
+            chatTitle: 'Scheduled Task',
+            message: JSON.stringify([{
+                type: "text",
+                text: taskPayload.message.replace('[SCHEDULED_TASK] ', '')
+            }])
+        });
+    }
+
+    return { success: true };
+};
+
+// Define cron schedule - runs every minute to check for due tasks
+handler.CRON_SCHEDULE = "* * * * *";
+```
+
+## instructions.txt (LLM prompt)
+
+```
+Scheduled Tasks:
+
+Schedule task with delay:
+<scheduleTask>{"message": "Send weekly report", "delay": "1h"}</scheduleTask>
+
+Schedule at specific time:
+<scheduleTask>{"message": "Meeting reminder", "time": "2025-01-15T10:00:00Z"}</scheduleTask>
+
+Delay formats: "30" (minutes), "2h" (hours), "1d" (days)
+
+List all scheduled tasks:
+<getScheduledTasks/>
+
+Delete a scheduled task:
+<deleteScheduledTask>{"timestamp": 1704067200000}</deleteScheduledTask>
+```
+
+## Key Points
+
+1. **Time precision** - Scheduler works at minute-level, times are rounded
+2. **Task payload** - Use `[SCHEDULED_TASK]` prefix to identify in onCronjob
+3. **Creates new chat** - Task execution creates new chat conversation
+4. **Delete by timestamp** - Tasks are identified by their scheduled timestamp
+5. **CRON_SCHEDULE** - Define at end of onCronjob.js file