@tamyla/clodo-framework 4.3.5 → 4.4.1

package/dist/utilities/durable-objects/websocket-room.js

@@ -0,0 +1,223 @@
+/**
+ * WebSocket Room Durable Object
+ * Manages real-time WebSocket connections for a room/channel
+ * 
+ * @example
+ * const id = env.WEBSOCKET_ROOM.idFromName('room-123');
+ * const room = env.WEBSOCKET_ROOM.get(id);
+ * return room.fetch(request); // WebSocket upgrade
+ */
+
+import { DurableObjectBase } from './base.js';
+export class WebSocketRoom extends DurableObjectBase {
+  constructor(state, env) {
+    super(state, env);
+    this.sessions = new Map();
+  }
+  async fetch(request) {
+    await this.ensureInitialized();
+    const url = new URL(request.url);
+
+    // Handle WebSocket upgrade
+    if (request.headers.get('Upgrade') === 'websocket') {
+      return this.handleWebSocket(request);
+    }
+
+    // HTTP API endpoints
+    const action = url.pathname.split('/').pop();
+    switch (action) {
+      case 'broadcast':
+        return this.handleBroadcast(request);
+      case 'members':
+        return this.getMembers();
+      case 'state':
+        return this.getRoomState();
+      default:
+        return this.error('Use WebSocket connection or API endpoints', 400);
+    }
+  }
+  async handleWebSocket(request) {
+    const url = new URL(request.url);
+    const userId = url.searchParams.get('userId') || crypto.randomUUID();
+    const username = url.searchParams.get('username') || `User-${userId.slice(0, 8)}`;
+
+    // WebSocketPair is a Cloudflare Workers global
+    // eslint-disable-next-line no-undef
+    const pair = new WebSocketPair();
+    const [client, server] = Object.values(pair);
+
+    // Accept the WebSocket
+    this.state.acceptWebSocket(server, [userId]);
+
+    // Create session
+    const session = {
+      id: userId,
+      username,
+      connectedAt: Date.now(),
+      lastActivity: Date.now()
+    };
+    this.sessions.set(userId, session);
+
+    // Notify others
+    this.broadcast({
+      type: 'user_joined',
+      user: {
+        id: userId,
+        username
+      },
+      memberCount: this.sessions.size
+    }, userId);
+
+    // Send welcome message
+    server.send(JSON.stringify({
+      type: 'connected',
+      userId,
+      username,
+      memberCount: this.sessions.size
+    }));
+    return new Response(null, {
+      status: 101,
+      webSocket: client
+    });
+  }
+  async webSocketMessage(ws, message) {
+    const [userId] = this.state.getTags(ws);
+    const session = this.sessions.get(userId);
+    if (!session) return;
+    session.lastActivity = Date.now();
+    try {
+      const data = JSON.parse(message);
+      switch (data.type) {
+        case 'message':
+          this.broadcast({
+            type: 'message',
+            from: {
+              id: userId,
+              username: session.username
+            },
+            content: data.content,
+            timestamp: Date.now()
+          });
+          break;
+        case 'typing':
+          this.broadcast({
+            type: 'typing',
+            user: {
+              id: userId,
+              username: session.username
+            }
+          }, userId);
+          break;
+        case 'presence':
+          session.status = data.status;
+          this.broadcast({
+            type: 'presence_update',
+            user: {
+              id: userId,
+              username: session.username
+            },
+            status: data.status
+          }, userId);
+          break;
+        case 'sync_state':
+          // Sync shared state
+          if (data.state) {
+            await this.setState('sharedState', data.state);
+            this.broadcast({
+              type: 'state_sync',
+              state: data.state,
+              updatedBy: userId
+            }, userId);
+          }
+          break;
+        case 'get_state':
+          {
+            const state = await this.getState('sharedState', {});
+            ws.send(JSON.stringify({
+              type: 'state_sync',
+              state
+            }));
+            break;
+          }
+        default:
+          // Forward custom message types
+          this.broadcast({
+            ...data,
+            from: userId
+          }, userId);
+      }
+    } catch (error) {
+      ws.send(JSON.stringify({
+        type: 'error',
+        message: 'Invalid message format'
+      }));
+    }
+  }
+  async webSocketClose(ws, code, reason) {
+    const [userId] = this.state.getTags(ws);
+    const session = this.sessions.get(userId);
+    if (session) {
+      this.sessions.delete(userId);
+      this.broadcast({
+        type: 'user_left',
+        user: {
+          id: userId,
+          username: session.username
+        },
+        memberCount: this.sessions.size
+      });
+    }
+  }
+  async webSocketError(ws, error) {
+    const [userId] = this.state.getTags(ws);
+    console.error(`WebSocket error for ${userId}:`, error);
+    ws.close(1011, 'Internal error');
+  }
+
+  /**
+   * Broadcast message to all connected clients
+   * @param {Object} message - Message to broadcast
+   * @param {string} excludeUserId - Optional user ID to exclude
+   */
+  broadcast(message, excludeUserId = null) {
+    const messageStr = JSON.stringify(message);
+    for (const ws of this.state.getWebSockets()) {
+      const [userId] = this.state.getTags(ws);
+      if (excludeUserId && userId === excludeUserId) continue;
+      try {
+        ws.send(messageStr);
+      } catch (error) {
+        // Socket might be closed
+      }
+    }
+  }
+  async handleBroadcast(request) {
+    const body = await request.json();
+    this.broadcast(body);
+    return this.json({
+      success: true,
+      recipients: this.sessions.size
+    });
+  }
+  async getMembers() {
+    const members = Array.from(this.sessions.values()).map(s => ({
+      id: s.id,
+      username: s.username,
+      connectedAt: s.connectedAt,
+      status: s.status
+    }));
+    return this.json({
+      members,
+      count: members.length
+    });
+  }
+  async getRoomState() {
+    const sharedState = await this.getState('sharedState', {});
+    return this.json({
+      memberCount: this.sessions.size,
+      members: Array.from(this.sessions.keys()),
+      sharedState
+    });
+  }
+}
+export default WebSocketRoom;

package/dist/utilities/email/handler.js

@@ -0,0 +1,359 @@
+/**
+ * Email Workers Utilities
+ * Handle incoming emails with Email Workers
+ * 
+ * @example
+ * import { EmailHandler, EmailParser } from '@tamyla/clodo-framework/utilities/email';
+ * 
+ * export default {
+ *   async email(message, env) {
+ *     const handler = new EmailHandler(message, env);
+ *     
+ *     // Parse email
+ *     const parsed = await handler.parse();
+ *     console.log('From:', parsed.from);
+ *     console.log('Subject:', parsed.subject);
+ *     
+ *     // Forward with modifications
+ *     await handler.forward('forward@example.com', {
+ *       headers: { 'X-Processed': 'true' }
+ *     });
+ *   }
+ * }
+ */
+
+/**
+ * Email Handler for Email Workers
+ */
+export class EmailHandler {
+  /**
+   * @param {EmailMessage} message - Email message from worker
+   * @param {Object} env - Environment bindings
+   */
+  constructor(message, env) {
+    this.message = message;
+    this.env = env;
+    this._parsed = null;
+  }
+
+  /**
+   * Get sender address
+   */
+  get from() {
+    return this.message.from;
+  }
+
+  /**
+   * Get recipient address
+   */
+  get to() {
+    return this.message.to;
+  }
+
+  /**
+   * Get raw email size in bytes
+   */
+  get size() {
+    return this.message.rawSize;
+  }
+
+  /**
+   * Get email headers
+   */
+  get headers() {
+    return this.message.headers;
+  }
+
+  /**
+   * Parse email content
+   * @returns {Promise<Object>} Parsed email
+   */
+  async parse() {
+    if (this._parsed) return this._parsed;
+    const parser = new EmailParser();
+    this._parsed = await parser.parse(this.message);
+    return this._parsed;
+  }
+
+  /**
+   * Forward email to another address
+   * @param {string} to - Destination address
+   * @param {Object} options - Forward options
+   */
+  async forward(to, options = {}) {
+    const headers = new Headers(this.message.headers);
+
+    // Add custom headers
+    if (options.headers) {
+      Object.entries(options.headers).forEach(([key, value]) => {
+        headers.set(key, value);
+      });
+    }
+    await this.message.forward(to, headers);
+  }
+
+  /**
+   * Reply to the email (requires send capability)
+   * @param {Object} options - Reply options
+   */
+  async reply(options = {}) {
+    if (!this.env.SEND_EMAIL) {
+      throw new Error('SEND_EMAIL binding required for replies');
+    }
+    const parsed = await this.parse();
+    const email = new EmailBuilder().from(options.from || this.to).to(this.from).subject(`Re: ${parsed.subject}`).text(options.text || '').html(options.html);
+
+    // Add In-Reply-To header
+    if (parsed.messageId) {
+      email.header('In-Reply-To', parsed.messageId);
+      email.header('References', parsed.messageId);
+    }
+    await this.env.SEND_EMAIL.send(email.build());
+  }
+
+  /**
+   * Reject the email
+   * @param {string} reason - Rejection reason
+   */
+  async reject(reason = 'Message rejected') {
+    await this.message.setReject(reason);
+  }
+
+  /**
+   * Get raw email content
+   * @returns {Promise<ReadableStream>}
+   */
+  async raw() {
+    return this.message.raw;
+  }
+
+  /**
+   * Get raw email as text
+   * @returns {Promise<string>}
+   */
+  async rawText() {
+    const raw = await this.raw();
+    const reader = raw.getReader();
+    const chunks = [];
+
+    // eslint-disable-next-line no-constant-condition
+    while (true) {
+      const {
+        done,
+        value
+      } = await reader.read();
+      if (done) break;
+      chunks.push(value);
+    }
+    return new TextDecoder().decode(new Uint8Array(chunks.flatMap(c => [...c])));
+  }
+}
+
+/**
+ * Email Parser
+ */
+export class EmailParser {
+  /**
+   * Parse an email message
+   * @param {EmailMessage} message
+   * @returns {Promise<Object>}
+   */
+  async parse(message) {
+    const headers = message.headers;
+    const rawText = await this._getRawText(message);
+
+    // Parse headers
+    const subject = headers.get('subject') || '';
+    const from = this._parseAddress(headers.get('from') || message.from);
+    const to = this._parseAddresses(headers.get('to') || message.to);
+    const cc = this._parseAddresses(headers.get('cc') || '');
+    const date = new Date(headers.get('date') || Date.now());
+    const messageId = headers.get('message-id');
+
+    // Parse body
+    const {
+      text,
+      html,
+      attachments
+    } = this._parseBody(rawText, headers);
+    return {
+      messageId,
+      from,
+      to,
+      cc,
+      subject,
+      date,
+      text,
+      html,
+      attachments,
+      headers: Object.fromEntries(headers.entries())
+    };
+  }
+  async _getRawText(message) {
+    const raw = await message.raw;
+    const reader = raw.getReader();
+    const chunks = [];
+
+    // eslint-disable-next-line no-constant-condition
+    while (true) {
+      const {
+        done,
+        value
+      } = await reader.read();
+      if (done) break;
+      chunks.push(value);
+    }
+    return new TextDecoder().decode(new Uint8Array(chunks.flatMap(c => [...c])));
+  }
+  _parseAddress(address) {
+    const match = address.match(/(?:"?([^"]*)"?\s)?<?([^>]+@[^>]+)>?/);
+    if (match) {
+      return {
+        name: match[1]?.trim() || '',
+        email: match[2].trim()
+      };
+    }
+    return {
+      name: '',
+      email: address.trim()
+    };
+  }
+  _parseAddresses(addresses) {
+    if (!addresses) return [];
+    return addresses.split(',').map(a => this._parseAddress(a.trim()));
+  }
+  _parseBody(rawText, headers) {
+    const contentType = headers.get('content-type') || 'text/plain';
+    const result = {
+      text: '',
+      html: '',
+      attachments: []
+    };
+
+    // Simple parsing - for complex emails, use a proper MIME parser
+    if (contentType.includes('multipart')) {
+      const boundary = this._getBoundary(contentType);
+      if (boundary) {
+        const parts = rawText.split(`--${boundary}`);
+        for (const part of parts) {
+          if (part.includes('Content-Type: text/plain')) {
+            result.text = this._extractContent(part);
+          } else if (part.includes('Content-Type: text/html')) {
+            result.html = this._extractContent(part);
+          } else if (part.includes('Content-Disposition: attachment')) {
+            result.attachments.push(this._parseAttachment(part));
+          }
+        }
+      }
+    } else if (contentType.includes('text/html')) {
+      result.html = rawText.split('\r\n\r\n').slice(1).join('\r\n\r\n');
+    } else {
+      result.text = rawText.split('\r\n\r\n').slice(1).join('\r\n\r\n');
+    }
+    return result;
+  }
+  _getBoundary(contentType) {
+    const match = contentType.match(/boundary=["']?([^"'\s;]+)["']?/);
+    return match ? match[1] : null;
+  }
+  _extractContent(part) {
+    const lines = part.split('\r\n');
+    const bodyStart = lines.findIndex(l => l === '') + 1;
+    return lines.slice(bodyStart).join('\r\n').trim();
+  }
+  _parseAttachment(part) {
+    const filenameMatch = part.match(/filename=["']?([^"'\r\n]+)["']?/);
+    const contentTypeMatch = part.match(/Content-Type:\s*([^\r\n;]+)/);
+    return {
+      filename: filenameMatch ? filenameMatch[1] : 'attachment',
+      contentType: contentTypeMatch ? contentTypeMatch[1].trim() : 'application/octet-stream',
+      content: this._extractContent(part)
+    };
+  }
+}
+
+/**
+ * Email Builder for sending emails
+ */
+export class EmailBuilder {
+  constructor() {
+    this._from = '';
+    this._to = [];
+    this._cc = [];
+    this._bcc = [];
+    this._subject = '';
+    this._text = '';
+    this._html = '';
+    this._headers = new Map();
+    this._attachments = [];
+  }
+  from(address) {
+    this._from = address;
+    return this;
+  }
+  to(address) {
+    this._to = Array.isArray(address) ? address : [address];
+    return this;
+  }
+  cc(address) {
+    this._cc = Array.isArray(address) ? address : [address];
+    return this;
+  }
+  bcc(address) {
+    this._bcc = Array.isArray(address) ? address : [address];
+    return this;
+  }
+  subject(subject) {
+    this._subject = subject;
+    return this;
+  }
+  text(text) {
+    this._text = text;
+    return this;
+  }
+  html(html) {
+    this._html = html;
+    return this;
+  }
+  header(key, value) {
+    this._headers.set(key, value);
+    return this;
+  }
+  attachment(filename, content, contentType = 'application/octet-stream') {
+    this._attachments.push({
+      filename,
+      content,
+      contentType
+    });
+    return this;
+  }
+  build() {
+    return {
+      personalizations: [{
+        to: this._to.map(email => ({
+          email
+        })),
+        cc: this._cc.length ? this._cc.map(email => ({
+          email
+        })) : undefined,
+        bcc: this._bcc.length ? this._bcc.map(email => ({
+          email
+        })) : undefined
+      }],
+      from: {
+        email: this._from
+      },
+      subject: this._subject,
+      content: [this._text ? {
+        type: 'text/plain',
+        value: this._text
+      } : null, this._html ? {
+        type: 'text/html',
+        value: this._html
+      } : null].filter(Boolean),
+      headers: Object.fromEntries(this._headers),
+      attachments: this._attachments.length ? this._attachments : undefined
+    };
+  }
+}
+export default EmailHandler;

package/dist/utilities/email/index.js

@@ -0,0 +1,6 @@
+/**
+ * Email Utilities
+ * @module @tamyla/clodo-framework/utilities/email
+ */
+
+export { EmailHandler, EmailParser, EmailBuilder } from './handler.js';

package/dist/utilities/index.js

@@ -0,0 +1,65 @@
+/**
+ * Clodo Framework Utilities
+ * 
+ * Runtime utilities for Cloudflare Workers services.
+ * All utilities are Worker-compatible (no Node.js dependencies).
+ * 
+ * @module @tamyla/clodo-framework/utilities
+ */
+
+// ============================================================
+// STORAGE UTILITIES
+// ============================================================
+
+// R2 Storage
+export { R2Storage, handleFileUpload, serveFile } from './storage/index.js';
+
+// KV Storage
+export { KVStorage, KVCache, KVWithMetadata } from './kv/index.js';
+
+// ============================================================
+// COMPUTE UTILITIES
+// ============================================================
+
+// Durable Objects
+export { DurableObjectBase, RateLimiter, SessionStore, Counter, WebSocketRoom } from './durable-objects/index.js';
+
+// Queues
+export { QueueProducer, QueueConsumer, MessageBuilder, createMessage, MessageTypes } from './queues/index.js';
+
+// Scheduled/Cron
+export { ScheduledHandler, CronJob, JobScheduler, ScheduledJobRegistry } from './scheduled/index.js';
+
+// ============================================================
+// AI & DATA UTILITIES
+// ============================================================
+
+// Workers AI
+export { AIClient, Models, createSSEStream, streamResponse } from './ai/index.js';
+
+// Vectorize (Vector Database)
+export { VectorStore, VectorSearch, EmbeddingHelper } from './vectorize/index.js';
+
+// ============================================================
+// CACHE & DATA UTILITIES
+// ============================================================
+
+// Upstash Redis
+export { UpstashRedis, UpstashCache, SessionManager, RateLimiter as RedisRateLimiter, Leaderboard } from './cache/index.js';
+
+// ============================================================
+// COMMUNICATION UTILITIES
+// ============================================================
+
+// Email Workers
+export { EmailHandler, EmailParser, EmailBuilder } from './email/index.js';
+
+// Service Bindings (inter-service communication)
+export { ServiceBindingClient, RPCClient, ServiceRouter } from './bindings/index.js';
+
+// ============================================================
+// OBSERVABILITY UTILITIES
+// ============================================================
+
+// Analytics Engine
+export { AnalyticsWriter, EventTracker, MetricsCollector } from './analytics/index.js';

package/dist/utilities/kv/index.js

@@ -0,0 +1,6 @@
+/**
+ * KV Storage Utilities
+ * @module @tamyla/clodo-framework/utilities/kv
+ */
+
+export { KVStorage, KVCache, KVWithMetadata } from './storage.js';