openkbs 0.0.64 → 0.0.66

package/elastic/pulse.md

@@ -0,0 +1,386 @@
+# Tutorial 14: Real-time with Pulse
+
+Add real-time features to your app with Pulse WebSocket messaging. Build live updates, chat, presence tracking, and collaborative features.
+
+## Enable Pulse
+
+```bash
+openkbs pulse enable
+```
+
+## How It Works
+
+```
+┌──────────────┐     ┌──────────────┐     ┌──────────────┐
+│   Browser 1  │     │    Pulse     │     │   Browser 2  │
+│              │────▶│   Server     │────▶│              │
+│  Subscribe   │     │              │     │  Receive     │
+│  to 'posts'  │     │              │     │  message     │
+└──────────────┘     └──────────────┘     └──────────────┘
+                            ▲
+                            │ Publish
+                     ┌──────────────┐
+                     │   Lambda     │
+                     │   Function   │
+                     └──────────────┘
+```
+
+1. Clients connect via WebSocket and subscribe to channels
+2. Your Lambda publishes events to channels
+3. All subscribers receive the message instantly
+
+## Client SDK (Browser)
+
+### Install
+
+```html
+<script src="https://unpkg.com/openkbs-pulse@2.0.1/pulse.js"></script>
+```
+
+Or with npm:
+```bash
+npm install openkbs-pulse
+```
+
+### Connect
+
+```javascript
+// Get token from your API (see Server SDK below)
+const { token, endpoint, kbId } = await fetch('/auth', {
+    method: 'POST',
+    body: JSON.stringify({ action: 'getPulseToken', userId: 'user123' })
+}).then(r => r.json());
+
+// Connect to Pulse
+const realtime = new Pulse.Realtime({
+    kbId,
+    token,
+    endpoint,
+    clientId: 'user123'
+});
+
+// Connection events
+realtime.connection.on('connected', () => console.log('Connected!'));
+realtime.connection.on('disconnected', () => console.log('Disconnected'));
+```
+
+### Subscribe to Channel
+
+```javascript
+const channel = realtime.channels.get('posts');
+
+// Subscribe to specific event
+channel.subscribe('new_post', (message) => {
+    console.log('New post:', message.data);
+});
+
+// Subscribe to all events
+channel.subscribe((message) => {
+    console.log('Event:', message.name, message.data);
+});
+```
+
+### Presence (Who's Online)
+
+```javascript
+const channel = realtime.channels.get('posts');
+
+// Enter presence with data
+channel.presence.enter({ name: 'Alice', avatar: '/alice.jpg' });
+
+// Get current members
+channel.presence.get((members) => {
+    console.log('Online:', members.length);
+    members.forEach(m => console.log(m.data.name));
+});
+
+// Subscribe to presence changes
+channel.presence.subscribe((members) => {
+    console.log('Members updated:', members);
+});
+
+// Specific events
+channel.presence.subscribe('enter', (member) => {
+    console.log(`${member.data.name} joined`);
+});
+
+channel.presence.subscribe('leave', (member) => {
+    console.log(`${member.data.name} left`);
+});
+
+// Leave when done
+channel.presence.leave();
+```
+
+### Disconnect
+
+```javascript
+realtime.close();
+```
+
+## Server SDK (Lambda)
+
+### Generate Token
+
+Your Lambda must generate tokens for clients:
+
+```javascript
+import pulse from 'openkbs-pulse/server';
+
+export async function handler(event) {
+    const { action, userId } = JSON.parse(event.body || '{}');
+    const kbId = process.env.OPENKBS_KB_ID;
+    const apiKey = process.env.OPENKBS_API_KEY;
+
+    if (action === 'getPulseToken') {
+        const tokenData = await pulse.getToken(kbId, apiKey, userId);
+        return {
+            statusCode: 200,
+            body: JSON.stringify({
+                token: tokenData.token,
+                endpoint: tokenData.endpoint,
+                kbId
+            })
+        };
+    }
+}
+```
+
+### Publish Events
+
+```javascript
+import pulse from 'openkbs-pulse/server';
+
+export async function handler(event) {
+    const { action, ...data } = JSON.parse(event.body || '{}');
+    const kbId = process.env.OPENKBS_KB_ID;
+    const apiKey = process.env.OPENKBS_API_KEY;
+
+    if (action === 'createPost') {
+        // Save to database...
+        const post = { id: 1, title: data.title, content: data.content };
+
+        // Publish to all subscribers
+        await pulse.publish('posts', 'new_post', { post }, { kbId, apiKey });
+
+        return { statusCode: 200, body: JSON.stringify({ post }) };
+    }
+}
+```
+
+### Get Presence
+
+```javascript
+const presence = await pulse.presence('posts', { kbId, apiKey });
+console.log('Online count:', presence.count);
+console.log('Members:', presence.members);
+```
+
+## Complete Example
+
+### Backend (posts/index.mjs)
+
+```javascript
+import pg from 'pg';
+import pulse from 'openkbs-pulse/server';
+
+const db = new pg.Client({ connectionString: process.env.DATABASE_URL });
+let connected = false;
+
+export async function handler(event) {
+    if (!connected) {
+        await db.connect();
+        connected = true;
+        await db.query(`
+            CREATE TABLE IF NOT EXISTS posts (
+                id SERIAL PRIMARY KEY,
+                user_name TEXT,
+                content TEXT,
+                created_at TIMESTAMP DEFAULT NOW()
+            )
+        `);
+    }
+
+    const headers = {
+        'Content-Type': 'application/json',
+        'Access-Control-Allow-Origin': '*',
+        'Access-Control-Allow-Headers': 'Content-Type'
+    };
+
+    if (event.requestContext?.http?.method === 'OPTIONS') {
+        return { statusCode: 200, headers, body: '' };
+    }
+
+    const { action, ...data } = JSON.parse(event.body || '{}');
+    const kbId = process.env.OPENKBS_KB_ID;
+    const apiKey = process.env.OPENKBS_API_KEY;
+
+    switch (action) {
+        case 'getPulseToken': {
+            const tokenData = await pulse.getToken(kbId, apiKey, data.userId);
+            return {
+                statusCode: 200,
+                headers,
+                body: JSON.stringify({ ...tokenData, kbId })
+            };
+        }
+
+        case 'list': {
+            const { rows } = await db.query(
+                'SELECT * FROM posts ORDER BY created_at DESC LIMIT 50'
+            );
+            return { statusCode: 200, headers, body: JSON.stringify({ posts: rows }) };
+        }
+
+        case 'create': {
+            const result = await db.query(
+                'INSERT INTO posts (user_name, content) VALUES ($1, $2) RETURNING *',
+                [data.userName, data.content]
+            );
+            const post = result.rows[0];
+
+            // Broadcast to all subscribers
+            await pulse.publish('posts', 'new_post', { post }, { kbId, apiKey });
+
+            return { statusCode: 200, headers, body: JSON.stringify({ post }) };
+        }
+
+        case 'presence': {
+            const result = await pulse.presence('posts', { kbId, apiKey });
+            return { statusCode: 200, headers, body: JSON.stringify(result) };
+        }
+
+        default:
+            return { statusCode: 400, headers, body: JSON.stringify({ error: 'Unknown action' }) };
+    }
+}
+```
+
+### Frontend
+
+```html
+<!DOCTYPE html>
+<html>
+<head>
+    <title>Live Posts</title>
+    <script src="https://unpkg.com/openkbs-pulse@2.0.1/pulse.js"></script>
+</head>
+<body>
+    <div id="online">Online: 0</div>
+    <div id="posts"></div>
+
+    <form id="form">
+        <input type="text" id="content" placeholder="What's on your mind?">
+        <button type="submit">Post</button>
+    </form>
+
+    <script>
+        const userId = 'user_' + Math.random().toString(36).substr(2, 9);
+        let realtime;
+
+        async function init() {
+            // Load existing posts
+            const { posts } = await fetch('/posts', {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ action: 'list' })
+            }).then(r => r.json());
+
+            posts.forEach(addPost);
+
+            // Get Pulse token
+            const { token, endpoint, kbId } = await fetch('/posts', {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ action: 'getPulseToken', userId })
+            }).then(r => r.json());
+
+            // Connect
+            realtime = new Pulse.Realtime({ kbId, token, endpoint, clientId: userId });
+
+            const channel = realtime.channels.get('posts');
+
+            // Subscribe to new posts
+            channel.subscribe('new_post', (msg) => {
+                addPost(msg.data.post);
+            });
+
+            // Presence
+            channel.presence.enter({ name: userId });
+            channel.presence.subscribe((members) => {
+                document.getElementById('online').textContent = 'Online: ' + members.length;
+            });
+        }
+
+        function addPost(post) {
+            const div = document.createElement('div');
+            div.innerHTML = `<b>${post.user_name}</b>: ${post.content}`;
+            document.getElementById('posts').prepend(div);
+        }
+
+        document.getElementById('form').addEventListener('submit', async (e) => {
+            e.preventDefault();
+            const content = document.getElementById('content').value;
+            if (!content) return;
+
+            await fetch('/posts', {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ action: 'create', content, userName: userId })
+            });
+
+            document.getElementById('content').value = '';
+        });
+
+        init();
+    </script>
+</body>
+</html>
+```
+
+## Private Channels
+
+For private messaging, use secret channel IDs:
+
+```javascript
+// Generate unique channel ID per user (store in database)
+const privateChannel = crypto.randomBytes(32).toString('hex');
+
+// User subscribes to their own private channel
+const myChannel = realtime.channels.get(user.privateChannel);
+myChannel.subscribe('message', (msg) => {
+    console.log('Private message:', msg.data);
+});
+
+// Server publishes to recipient's channel
+await pulse.publish(recipient.privateChannel, 'message', {
+    from: sender.name,
+    text: 'Hello!'
+}, { kbId, apiKey });
+```
+
+## CLI Reference
+
+```bash
+openkbs pulse enable               # Enable Pulse
+openkbs pulse status               # Check status
+openkbs pulse channels             # List active channels
+openkbs pulse presence <channel>   # View presence
+openkbs pulse publish <ch> "msg"   # Publish message
+openkbs pulse disable              # Disable
+```
+
+## Tips
+
+1. **Generate Tokens Server-Side** - Never expose your API key in frontend code.
+
+2. **Use Presence for Online Status** - Built-in, no database needed.
+
+3. **Private Channels** - Use random IDs for 1:1 messaging.
+
+4. **Reconnection** - SDK auto-reconnects with exponential backoff.
+
+## Next Steps
+
+- [Tutorial 15: Node.js Full Example](./15-nodejs-example.md)
+- [Tutorial 16: Java Example](./16-java-example.md)

package/elastic/storage.md

@@ -0,0 +1,291 @@
+# Tutorial 12: S3 Storage with CloudFront CDN
+
+Upload files, serve images, and host media with S3 storage and CloudFront CDN. Get presigned URLs for secure browser uploads.
+
+## Enable Storage
+
+```bash
+openkbs storage enable
+```
+
+Your S3 bucket is ready.
+
+## Check Status
+
+```bash
+openkbs storage status
+```
+
+Output:
+```
+Storage Status:
+  Enabled: true
+  Bucket: openkbs-elastic-abc123
+  Region: us-east-1
+  Public: false
+```
+
+## Add CloudFront CDN
+
+Serve files from your domain with edge caching:
+
+```bash
+openkbs storage cloudfront media
+```
+
+This maps:
+- S3 path `media/*` to URL `yourdomain.com/media/*`
+
+| S3 Key | Public URL |
+|--------|------------|
+| `media/photo.jpg` | `yourdomain.com/media/photo.jpg` |
+| `media/uploads/image.png` | `yourdomain.com/media/uploads/image.png` |
+
+## Upload Files
+
+### From CLI
+
+```bash
+openkbs storage put ./photo.jpg media/photo.jpg
+openkbs storage put ./document.pdf docs/document.pdf
+```
+
+### From Lambda (Presigned URL)
+
+Generate a presigned URL for browser uploads:
+
+```javascript
+import { S3Client, PutObjectCommand } from '@aws-sdk/client-s3';
+import { getSignedUrl } from '@aws-sdk/s3-request-presigner';
+
+const s3 = new S3Client({ region: process.env.STORAGE_REGION });
+
+export async function handler(event) {
+    const { action, fileName, contentType } = JSON.parse(event.body || '{}');
+
+    if (action === 'getUploadUrl') {
+        const bucket = process.env.STORAGE_BUCKET;
+
+        // Key must match CloudFront path prefix
+        const key = `media/uploads/${Date.now()}-${fileName}`;
+
+        const command = new PutObjectCommand({
+            Bucket: bucket,
+            Key: key,
+            ContentType: contentType || 'application/octet-stream'
+        });
+
+        const uploadUrl = await getSignedUrl(s3, command, { expiresIn: 3600 });
+
+        // Return relative URL for CloudFront
+        const publicUrl = `/${key}`;
+
+        return {
+            statusCode: 200,
+            body: JSON.stringify({ uploadUrl, publicUrl, key })
+        };
+    }
+}
+```
+
+`package.json`:
+```json
+{
+  "type": "module",
+  "dependencies": {
+    "@aws-sdk/client-s3": "^3.400.0",
+    "@aws-sdk/s3-request-presigner": "^3.400.0"
+  }
+}
+```
+
+### Browser Upload
+
+```javascript
+async function uploadFile(file) {
+    // 1. Get presigned URL from your API
+    const response = await fetch('/api', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+            action: 'getUploadUrl',
+            fileName: file.name,
+            contentType: file.type
+        })
+    });
+
+    const { uploadUrl, publicUrl } = await response.json();
+
+    // 2. Upload directly to S3
+    await fetch(uploadUrl, {
+        method: 'PUT',
+        body: file,
+        headers: { 'Content-Type': file.type }
+    });
+
+    // 3. Return the public URL
+    return publicUrl;  // e.g., /media/uploads/1234567890-photo.jpg
+}
+
+// Usage
+const fileInput = document.querySelector('input[type="file"]');
+fileInput.addEventListener('change', async (e) => {
+    const file = e.target.files[0];
+    const url = await uploadFile(file);
+    console.log('Uploaded to:', url);
+});
+```
+
+### Upload with Progress
+
+```javascript
+function uploadWithProgress(file, onProgress) {
+    return new Promise(async (resolve, reject) => {
+        const { uploadUrl, publicUrl } = await fetch('/api', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+                action: 'getUploadUrl',
+                fileName: file.name,
+                contentType: file.type
+            })
+        }).then(r => r.json());
+
+        const xhr = new XMLHttpRequest();
+
+        xhr.upload.addEventListener('progress', (e) => {
+            if (e.lengthComputable) {
+                onProgress(Math.round((e.loaded / e.total) * 100));
+            }
+        });
+
+        xhr.addEventListener('load', () => {
+            if (xhr.status === 200) resolve(publicUrl);
+            else reject(new Error('Upload failed'));
+        });
+
+        xhr.addEventListener('error', reject);
+        xhr.open('PUT', uploadUrl);
+        xhr.setRequestHeader('Content-Type', file.type);
+        xhr.send(file);
+    });
+}
+
+// Usage
+const url = await uploadWithProgress(file, (percent) => {
+    console.log(`Upload: ${percent}%`);
+});
+```
+
+## List Files
+
+```bash
+openkbs storage ls
+openkbs storage ls media/
+openkbs storage ls media/uploads/ --limit 100
+```
+
+## Download Files
+
+```bash
+openkbs storage get media/photo.jpg
+openkbs storage get media/photo.jpg ./local-photo.jpg
+```
+
+## Delete Files
+
+```bash
+openkbs storage rm media/photo.jpg
+```
+
+## Make Bucket Public
+
+By default, buckets are private. To make files publicly accessible without presigned URLs:
+
+```bash
+openkbs storage public true
+```
+
+To make private again:
+```bash
+openkbs storage public false
+```
+
+## File Organization
+
+Recommended structure:
+```
+media/
+  images/
+    avatars/
+    posts/
+  videos/
+  documents/
+uploads/
+  temp/
+```
+
+## Python Example
+
+```python
+import json
+import os
+import boto3
+from botocore.config import Config
+
+s3 = boto3.client('s3',
+    region_name=os.environ.get('STORAGE_REGION', 'us-east-1'),
+    config=Config(signature_version='s3v4')
+)
+
+def handler(event, context):
+    body = json.loads(event.get('body', '{}'))
+    action = body.get('action')
+    bucket = os.environ['STORAGE_BUCKET']
+
+    if action == 'getUploadUrl':
+        import time
+        key = f"media/uploads/{int(time.time())}-{body['fileName']}"
+
+        url = s3.generate_presigned_url('put_object',
+            Params={'Bucket': bucket, 'Key': key, 'ContentType': body.get('contentType', 'application/octet-stream')},
+            ExpiresIn=3600
+        )
+
+        return {
+            'statusCode': 200,
+            'body': json.dumps({'uploadUrl': url, 'publicUrl': f'/{key}', 'key': key})
+        }
+
+    return {'statusCode': 400, 'body': json.dumps({'error': 'Unknown action'})}
+```
+
+## CLI Reference
+
+```bash
+openkbs storage enable                    # Enable storage
+openkbs storage status                    # Check status
+openkbs storage public true|false         # Set public access
+openkbs storage cloudfront <path>         # Add CloudFront path
+openkbs storage cloudfront remove <path>  # Remove CloudFront path
+openkbs storage ls [prefix]               # List files
+openkbs storage put <file> [key]          # Upload file
+openkbs storage get <key> [file]          # Download file
+openkbs storage rm <key>                  # Delete file
+openkbs storage disable --force           # Disable (DANGEROUS)
+```
+
+## Tips
+
+1. **Always Use Presigned URLs** - Don't send file data through your Lambda. Upload directly to S3.
+
+2. **Match CloudFront Path** - If CloudFront path is `media`, upload to `media/...` keys.
+
+3. **Use Content-Type** - Set correct MIME type for proper browser handling.
+
+4. **Versioned Filenames** - Use timestamps or UUIDs to avoid cache issues: `1704067200-photo.jpg`
+
+## Next Steps
+
+- [Tutorial 13: Serverless Functions](./13-functions.md)
+- [Tutorial 14: Real-time Pulse](./14-pulse.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openkbs",
-  "version": "0.0.64",
+  "version": "0.0.66",
   "description": "OpenKBS - Command Line Interface",
   "main": "src/index.js",
   "scripts": {