@tamyla/clodo-framework 4.3.5 → 4.4.0

package/CHANGELOG.md

@@ -1,3 +1,11 @@
+# [4.4.0](https://github.com/tamylaa/clodo-framework/compare/v4.3.5...v4.4.0) (2026-02-05)
+
+
+### Features
+
+* add comprehensive Cloudflare Workers utilities ([8c82fd9](https://github.com/tamylaa/clodo-framework/commit/8c82fd97b9f2ac7ea1e579b3a4a37fea9f0aaaab))
+* add comprehensive Cloudflare Workers utilities ([b7fd6e8](https://github.com/tamylaa/clodo-framework/commit/b7fd6e881cc6734606917b1786150abc5022f6ab))
+
 ## [4.3.5](https://github.com/tamylaa/clodo-framework/compare/v4.3.4...v4.3.5) (2026-02-04)
 
 

package/README.md

@@ -1,6 +1,6 @@
 # Clodo Framework
 
-[![Validate CI](https://github.com/tamylaa/clodo-framework/actions/workflows/validate-on-pr.yml/badge.svg)](https://github.com/tamylaa/clodo-framework/actions/workflows/validate-on-pr.yml) [![Full tests (nightly)](https://github.com/tamylaa/clodo-framework/actions/workflows/full-tests-nightly.yml/badge.svg)](https://github.com/tamylaa/clodo-framework/actions/workflows/full-tests-nightly.yml) [![npm](https://img.shields.io/npm/v/@tamyla/clodo-framework.svg)](https://www.npmjs.com/package/@tamyla/clodo-framework) [![downloads](https://img.shields.io/npm/dw/@tamyla/clodo-framework.svg)](https://www.npmjs.com/package/@tamyla/clodo-framework) [![License](https://img.shields.io/npm/l/@tamyla/clodo-framework.svg)](https://github.com/tamylaa/clodo-framework/blob/main/LICENSE) [![Sponsor](https://img.shields.io/github/sponsors/tamylaa?style=social)](https://github.com/sponsors/tamylaa) [![Support](https://img.shields.io/badge/Support-product%40clodo.dev-blue)](SUPPORT.md)
+[![Validate CI](https://github.com/tamylaa/clodo-framework/actions/workflows/validate-on-pr.yml/badge.svg)](https://github.com/tamylaa/clodo-framework/actions/workflows/validate-on-pr.yml) [![Full tests (nightly)](https://github.com/tamylaa/clodo-framework/actions/workflows/full-tests-nightly.yml/badge.svg)](https://github.com/tamylaa/clodo-framework/actions/workflows/full-tests-nightly.yml) [![npm](https://img.shields.io/npm/v/@tamyla/clodo-framework.svg)](https://www.npmjs.com/package/@tamyla/clodo-framework) [![downloads](https://img.shields.io/npm/dw/@tamyla/clodo-framework.svg)](https://www.npmjs.com/package/@tamyla/clodo-framework) [![License](https://img.shields.io/npm/l/@tamyla/clodo-framework.svg)](https://github.com/tamylaa/clodo-framework/blob/main/LICENSE) [![Sponsor](https://img.shields.io/github/sponsors/tamylaa?style=social)](https://github.com/sponsors/tamylaa) [![Support](https://img.shields.io/badge/Support-product%40clodo.dev-blue)](SUPPORT.md) [![BuyMeACoffee](https://img.shields.io/badge/Buy%20Me%20a%20Coffee-%E2%9D%A4-orange?logo=buy-me-a-coffee)](https://www.buymeacoffee.com/yourname) [![Patreon](https://img.shields.io/badge/Patreon-Support-orange?logo=patreon)](https://www.patreon.com/yourname) [![PayPal](https://img.shields.io/badge/PayPal-Donate-blue?logo=paypal)](https://paypal.me/yourname)
 
 ## 🚀 Production-Ready: Promise Delivered
 
@@ -46,6 +46,8 @@ Your feedback helps prioritize improvements and signals others that this project
 
 - **Support & SLAs:** See [SUPPORT.md](SUPPORT.md) for response times and escalation procedures.
 
+- **Donate / Sponsor:** If you'd like to support ongoing maintenance and improvements, please see [FUNDING.md](FUNDING.md) for ways to contribute (GitHub Sponsors, Open Collective, PayPal, Buy Me a Coffee, Patreon).
+
 ### 📁 **Documentation Structure**
 ```
 ├── docs/                    # 📖 Public documentation (npm package)

package/dist/utilities/ai/client.js

@@ -0,0 +1,276 @@
+/**
+ * Workers AI Client
+ * Provides convenient methods for working with Cloudflare Workers AI
+ * 
+ * @example
+ * import { AIClient, Models } from '@tamyla/clodo-framework/utilities/ai';
+ * 
+ * const ai = new AIClient(env.AI);
+ * const response = await ai.chat([
+ *   { role: 'user', content: 'Hello!' }
+ * ]);
+ */
+
+/**
+ * Default models for different tasks
+ */
+export const Models = {
+  // Text Generation
+  TEXT_GENERATION: '@cf/meta/llama-3.1-8b-instruct',
+  TEXT_GENERATION_FAST: '@cf/meta/llama-3.1-8b-instruct-fast',
+  TEXT_GENERATION_LARGE: '@cf/meta/llama-3.1-70b-instruct',
+  // Code Generation
+  CODE_GENERATION: '@hf/thebloke/deepseek-coder-6.7b-instruct-awq',
+  // Chat
+  CHAT: '@cf/meta/llama-3.1-8b-instruct',
+  // Embeddings
+  EMBEDDINGS: '@cf/baai/bge-base-en-v1.5',
+  EMBEDDINGS_LARGE: '@cf/baai/bge-large-en-v1.5',
+  // Image Generation
+  IMAGE_GENERATION: '@cf/stabilityai/stable-diffusion-xl-base-1.0',
+  IMAGE_GENERATION_FAST: '@cf/lykon/dreamshaper-8-lcm',
+  // Image Classification
+  IMAGE_CLASSIFICATION: '@cf/microsoft/resnet-50',
+  // Speech to Text
+  SPEECH_TO_TEXT: '@cf/openai/whisper',
+  SPEECH_TO_TEXT_TINY: '@cf/openai/whisper-tiny-en',
+  // Translation
+  TRANSLATION: '@cf/meta/m2m100-1.2b',
+  // Summarization
+  SUMMARIZATION: '@cf/facebook/bart-large-cnn',
+  // Sentiment Analysis
+  SENTIMENT: '@cf/huggingface/distilbert-sst-2-int8',
+  // Object Detection
+  OBJECT_DETECTION: '@cf/facebook/detr-resnet-50'
+};
+
+/**
+ * AI Client for Workers AI
+ */
+export class AIClient {
+  /**
+   * @param {Object} ai - AI binding from env
+   * @param {Object} options - Client options
+   */
+  constructor(ai, options = {}) {
+    if (!ai) {
+      throw new Error('AI binding is required');
+    }
+    this.ai = ai;
+    this.options = {
+      defaultModel: Models.CHAT,
+      maxTokens: 1024,
+      temperature: 0.7,
+      ...options
+    };
+  }
+
+  /**
+   * Run a model directly
+   */
+  async run(model, inputs) {
+    return this.ai.run(model, inputs);
+  }
+
+  /**
+   * Generate text from a prompt
+   */
+  async generateText(prompt, options = {}) {
+    const model = options.model || this.options.defaultModel;
+    const response = await this.ai.run(model, {
+      prompt,
+      max_tokens: options.maxTokens || this.options.maxTokens,
+      temperature: options.temperature || this.options.temperature,
+      ...(options.stream && {
+        stream: true
+      })
+    });
+    if (options.stream) {
+      return response;
+    }
+    return response.response || response;
+  }
+
+  /**
+   * Chat completion with message history
+   */
+  async chat(messages, options = {}) {
+    const model = options.model || Models.CHAT;
+    const response = await this.ai.run(model, {
+      messages,
+      max_tokens: options.maxTokens || this.options.maxTokens,
+      temperature: options.temperature || this.options.temperature,
+      ...(options.stream && {
+        stream: true
+      })
+    });
+    if (options.stream) {
+      return response;
+    }
+    return response.response || response;
+  }
+
+  /**
+   * Generate embeddings for text
+   */
+  async embed(text, options = {}) {
+    const model = options.model || Models.EMBEDDINGS;
+    const texts = Array.isArray(text) ? text : [text];
+    const response = await this.ai.run(model, {
+      text: texts
+    });
+    return response.data || response;
+  }
+
+  /**
+   * Generate an image from a prompt
+   */
+  async generateImage(prompt, options = {}) {
+    const model = options.model || Models.IMAGE_GENERATION;
+    const response = await this.ai.run(model, {
+      prompt,
+      negative_prompt: options.negativePrompt,
+      height: options.height || 1024,
+      width: options.width || 1024,
+      num_steps: options.steps || 20,
+      guidance: options.guidance || 7.5
+    });
+    return response;
+  }
+
+  /**
+   * Classify an image
+   */
+  async classifyImage(image, options = {}) {
+    const model = options.model || Models.IMAGE_CLASSIFICATION;
+    const response = await this.ai.run(model, {
+      image: Array.isArray(image) ? image : [...new Uint8Array(image)]
+    });
+    return response;
+  }
+
+  /**
+   * Detect objects in an image
+   */
+  async detectObjects(image, options = {}) {
+    const model = options.model || Models.OBJECT_DETECTION;
+    const response = await this.ai.run(model, {
+      image: Array.isArray(image) ? image : [...new Uint8Array(image)]
+    });
+    return response;
+  }
+
+  /**
+   * Transcribe audio to text
+   */
+  async transcribe(audio, options = {}) {
+    const model = options.model || Models.SPEECH_TO_TEXT;
+    const response = await this.ai.run(model, {
+      audio: Array.isArray(audio) ? audio : [...new Uint8Array(audio)]
+    });
+    return response;
+  }
+
+  /**
+   * Translate text
+   */
+  async translate(text, sourceLang, targetLang, options = {}) {
+    const model = options.model || Models.TRANSLATION;
+    const response = await this.ai.run(model, {
+      text,
+      source_lang: sourceLang,
+      target_lang: targetLang
+    });
+    return response.translated_text || response;
+  }
+
+  /**
+   * Summarize text
+   */
+  async summarize(text, options = {}) {
+    const model = options.model || Models.SUMMARIZATION;
+    const response = await this.ai.run(model, {
+      input_text: text,
+      max_length: options.maxLength || 150
+    });
+    return response.summary || response;
+  }
+
+  /**
+   * Analyze sentiment of text
+   */
+  async analyzeSentiment(text, options = {}) {
+    const model = options.model || Models.SENTIMENT;
+    const response = await this.ai.run(model, {
+      text
+    });
+    return response;
+  }
+
+  /**
+   * Calculate similarity between texts using embeddings
+   */
+  async similarity(text1, text2) {
+    const embeddings = await this.embed([text1, text2]);
+    return this.cosineSimilarity(embeddings[0], embeddings[1]);
+  }
+
+  /**
+   * Calculate cosine similarity between two vectors
+   */
+  cosineSimilarity(a, b) {
+    let dotProduct = 0;
+    let normA = 0;
+    let normB = 0;
+    for (let i = 0; i < a.length; i++) {
+      dotProduct += a[i] * b[i];
+      normA += a[i] * a[i];
+      normB += b[i] * b[i];
+    }
+    return dotProduct / (Math.sqrt(normA) * Math.sqrt(normB));
+  }
+}
+
+/**
+ * Create an SSE stream from AI stream response
+ */
+export function createSSEStream(stream) {
+  const encoder = new TextEncoder();
+  return new ReadableStream({
+    async start(controller) {
+      const reader = stream.getReader();
+      try {
+        // eslint-disable-next-line no-constant-condition
+        while (true) {
+          const {
+            done,
+            value
+          } = await reader.read();
+          if (done) break;
+          const text = typeof value === 'string' ? value : new TextDecoder().decode(value);
+          controller.enqueue(encoder.encode(`data: ${JSON.stringify({
+            text
+          })}\n\n`));
+        }
+        controller.enqueue(encoder.encode('data: [DONE]\n\n'));
+        controller.close();
+      } catch (error) {
+        controller.error(error);
+      }
+    }
+  });
+}
+
+/**
+ * Create a streaming response for AI output
+ */
+export function streamResponse(stream) {
+  return new Response(createSSEStream(stream), {
+    headers: {
+      'Content-Type': 'text/event-stream',
+      'Cache-Control': 'no-cache',
+      'Connection': 'keep-alive'
+    }
+  });
+}
+export default AIClient;

package/dist/utilities/ai/index.js

@@ -0,0 +1,6 @@
+/**
+ * AI Utilities
+ * @module @tamyla/clodo-framework/utilities/ai
+ */
+
+export { AIClient, Models, createSSEStream, streamResponse } from './client.js';

package/dist/utilities/analytics/index.js

@@ -0,0 +1,6 @@
+/**
+ * Analytics Engine Utilities
+ * @module @tamyla/clodo-framework/utilities/analytics
+ */
+
+export { AnalyticsWriter, EventTracker, MetricsCollector } from './writer.js';

package/dist/utilities/analytics/writer.js

@@ -0,0 +1,226 @@
+/**
+ * Analytics Engine Utilities
+ * Write events to Cloudflare Analytics Engine
+ * 
+ * @example
+ * import { AnalyticsWriter, EventTracker } from '@tamyla/clodo-framework/utilities/analytics';
+ * 
+ * const analytics = new AnalyticsWriter(env.ANALYTICS);
+ * 
+ * // Write a data point
+ * analytics.write({
+ *   indexes: ['user-123'],
+ *   blobs: ['page_view', '/home'],
+ *   doubles: [Date.now()],
+ * });
+ * 
+ * // Use event tracker for common patterns
+ * const tracker = new EventTracker(env.ANALYTICS);
+ * tracker.pageView('/home', { userId: '123', referrer: 'google.com' });
+ * tracker.event('button_click', { buttonId: 'signup' });
+ */
+
+/**
+ * Analytics Engine Writer
+ */
+export class AnalyticsWriter {
+  /**
+   * @param {AnalyticsEngineDataset} dataset - Analytics Engine binding
+   */
+  constructor(dataset) {
+    if (!dataset) {
+      throw new Error('Analytics Engine dataset binding is required');
+    }
+    this.dataset = dataset;
+  }
+
+  /**
+   * Write a data point to Analytics Engine
+   * @param {Object} dataPoint - Data point to write
+   * @param {string[]} dataPoint.indexes - Index values (up to 1)
+   * @param {string[]} dataPoint.blobs - Blob values (up to 20)
+   * @param {number[]} dataPoint.doubles - Double values (up to 20)
+   */
+  write(dataPoint) {
+    this.dataset.writeDataPoint({
+      indexes: dataPoint.indexes || [],
+      blobs: dataPoint.blobs || [],
+      doubles: dataPoint.doubles || []
+    });
+  }
+
+  /**
+   * Write multiple data points
+   * @param {Array<Object>} dataPoints
+   */
+  writeBatch(dataPoints) {
+    for (const dataPoint of dataPoints) {
+      this.write(dataPoint);
+    }
+  }
+}
+
+/**
+ * High-level event tracker
+ */
+export class EventTracker {
+  constructor(dataset, options = {}) {
+    this.writer = new AnalyticsWriter(dataset);
+    this.defaultIndex = options.defaultIndex || '';
+    this.includeTimestamp = options.includeTimestamp !== false;
+  }
+
+  /**
+   * Track a page view
+   */
+  pageView(path, properties = {}) {
+    this.writer.write({
+      indexes: [properties.userId || this.defaultIndex],
+      blobs: ['page_view', path, properties.referrer || '', properties.userAgent || '', properties.country || ''],
+      doubles: this.includeTimestamp ? [Date.now()] : []
+    });
+  }
+
+  /**
+   * Track a custom event
+   */
+  event(eventName, properties = {}) {
+    const blobs = ['event', eventName, JSON.stringify(properties).slice(0, 1024) // Truncate if too long
+    ];
+    this.writer.write({
+      indexes: [properties.userId || this.defaultIndex],
+      blobs,
+      doubles: this.includeTimestamp ? [Date.now(), properties.value || 0] : [properties.value || 0]
+    });
+  }
+
+  /**
+   * Track an error
+   */
+  error(errorType, message, properties = {}) {
+    this.writer.write({
+      indexes: [properties.userId || this.defaultIndex],
+      blobs: ['error', errorType, message.slice(0, 1024), properties.stack?.slice(0, 1024) || '', properties.path || ''],
+      doubles: this.includeTimestamp ? [Date.now()] : []
+    });
+  }
+
+  /**
+   * Track API request
+   */
+  apiRequest(method, path, properties = {}) {
+    this.writer.write({
+      indexes: [properties.userId || this.defaultIndex],
+      blobs: ['api_request', method, path, properties.status?.toString() || '', properties.error || ''],
+      doubles: [Date.now(), properties.duration || 0, properties.status || 0, properties.responseSize || 0]
+    });
+  }
+
+  /**
+   * Track user action
+   */
+  userAction(action, target, properties = {}) {
+    this.writer.write({
+      indexes: [properties.userId || this.defaultIndex],
+      blobs: ['user_action', action, target, properties.label || '', properties.category || ''],
+      doubles: this.includeTimestamp ? [Date.now(), properties.value || 0] : [properties.value || 0]
+    });
+  }
+}
+
+/**
+ * Metrics collector for performance monitoring
+ */
+export class MetricsCollector {
+  constructor(dataset, options = {}) {
+    this.writer = new AnalyticsWriter(dataset);
+    this.serviceName = options.serviceName || 'worker';
+    this.buffer = [];
+    this.flushInterval = options.flushInterval || 1000;
+    this.maxBufferSize = options.maxBufferSize || 100;
+  }
+
+  /**
+   * Record a timing metric
+   */
+  timing(name, durationMs, tags = {}) {
+    this._addToBuffer({
+      type: 'timing',
+      name,
+      value: durationMs,
+      tags
+    });
+  }
+
+  /**
+   * Record a counter metric
+   */
+  counter(name, value = 1, tags = {}) {
+    this._addToBuffer({
+      type: 'counter',
+      name,
+      value,
+      tags
+    });
+  }
+
+  /**
+   * Record a gauge metric
+   */
+  gauge(name, value, tags = {}) {
+    this._addToBuffer({
+      type: 'gauge',
+      name,
+      value,
+      tags
+    });
+  }
+
+  /**
+   * Record request metrics
+   */
+  request(properties = {}) {
+    this.writer.write({
+      indexes: [this.serviceName],
+      blobs: ['request', properties.method || 'GET', properties.path || '/', properties.status?.toString() || '200', properties.colo || ''],
+      doubles: [Date.now(), properties.duration || 0, properties.status || 200, properties.requestSize || 0, properties.responseSize || 0]
+    });
+  }
+
+  /**
+   * Create a timer that records duration on stop
+   */
+  startTimer(name, tags = {}) {
+    const start = performance.now();
+    return {
+      stop: () => {
+        const duration = performance.now() - start;
+        this.timing(name, duration, tags);
+        return duration;
+      }
+    };
+  }
+  _addToBuffer(metric) {
+    this.buffer.push(metric);
+    if (this.buffer.length >= this.maxBufferSize) {
+      this.flush();
+    }
+  }
+
+  /**
+   * Flush buffered metrics
+   */
+  flush() {
+    if (this.buffer.length === 0) return;
+    const timestamp = Date.now();
+    for (const metric of this.buffer) {
+      this.writer.write({
+        indexes: [this.serviceName],
+        blobs: [metric.type, metric.name, JSON.stringify(metric.tags || {})],
+        doubles: [timestamp, metric.value]
+      });
+    }
+    this.buffer = [];
+  }
+}
+export default AnalyticsWriter;