@mastra/cloudflare 1.0.0-beta.9 → 1.1.0-alpha.0

package/README.md

@@ -11,7 +11,7 @@ npm install @mastra/cloudflare
 ## Prerequisites
 
 - Cloudflare account with KV namespaces set up
-- Node.js 16 or higher
+- Node.js 22.13.0 or later
 - (Optional) Cloudflare Worker for Workers API mode
 
 ## Usage

package/dist/docs/README.md

@@ -0,0 +1,31 @@
+# @mastra/cloudflare Documentation
+
+> Embedded documentation for coding agents
+
+## Quick Start
+
+```bash
+# Read the skill overview
+cat docs/SKILL.md
+
+# Get the source map
+cat docs/SOURCE_MAP.json
+
+# Read topic documentation
+cat docs/<topic>/01-overview.md
+```
+
+## Structure
+
+```
+docs/
+├── SKILL.md           # Entry point
+├── README.md          # This file
+├── SOURCE_MAP.json    # Export index
+├── storage/ (1 files)
+```
+
+## Version
+
+Package: @mastra/cloudflare
+Version: 1.1.0-alpha.0

package/dist/docs/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: mastra-cloudflare-docs
+description: Documentation for @mastra/cloudflare. Includes links to type definitions and readable implementation code in dist/.
+---
+
+# @mastra/cloudflare Documentation
+
+> **Version**: 1.1.0-alpha.0
+> **Package**: @mastra/cloudflare
+
+## Quick Navigation
+
+Use SOURCE_MAP.json to find any export:
+
+```bash
+cat docs/SOURCE_MAP.json
+```
+
+Each export maps to:
+- **types**: `.d.ts` file with JSDoc and API signatures
+- **implementation**: `.js` chunk file with readable source
+- **docs**: Conceptual documentation in `docs/`
+
+## Top Exports
+
+
+
+See SOURCE_MAP.json for the complete list.
+
+## Available Topics
+
+- [Storage](storage/) - 1 file(s)

package/dist/docs/SOURCE_MAP.json

@@ -0,0 +1,6 @@
+{
+  "version": "1.1.0-alpha.0",
+  "package": "@mastra/cloudflare",
+  "exports": {},
+  "modules": {}
+}

package/dist/docs/storage/01-reference.md

@@ -0,0 +1,67 @@
+# Storage API Reference
+
+> API reference for storage - 1 entries
+
+
+---
+
+## Reference: Cloudflare Storage
+
+> Documentation for the Cloudflare KV storage implementation in Mastra.
+
+The Cloudflare KV storage implementation provides a globally distributed, serverless key-value store solution using Cloudflare Workers KV.
+
+> **Observability Not Supported**
+Cloudflare KV storage **does not support the observability domain**. Traces from the `DefaultExporter` cannot be persisted to KV, and Mastra Studio's observability features won't work with Cloudflare KV as your only storage provider. To enable observability, use [composite storage](https://mastra.ai/reference/storage/composite#specialized-storage-for-observability) to route observability data to a supported provider like ClickHouse or PostgreSQL.
+
+## Installation
+
+```bash npm2yarn
+npm install @mastra/cloudflare@latest
+```
+
+## Usage
+
+```typescript
+import { CloudflareStore } from "@mastra/cloudflare";
+
+// --- Example 1: Using Workers Binding ---
+const storageWorkers = new CloudflareStore({
+  id: "cloudflare-workers-storage",
+  bindings: {
+    threads: THREADS_KV, // KVNamespace binding for threads table
+    messages: MESSAGES_KV, // KVNamespace binding for messages table
+    // Add other tables as needed
+  },
+  keyPrefix: "dev_", // Optional: isolate keys per environment
+});
+
+// --- Example 2: Using REST API ---
+const storageRest = new CloudflareStore({
+  id: "cloudflare-rest-storage",
+  accountId: process.env.CLOUDFLARE_ACCOUNT_ID!, // Cloudflare Account ID
+  apiToken: process.env.CLOUDFLARE_API_TOKEN!, // Cloudflare API Token
+  namespacePrefix: "dev_", // Optional: isolate namespaces per environment
+});
+```
+
+## Parameters
+
+#### Additional Notes
+
+### Schema Management
+
+The storage implementation handles schema creation and updates automatically. It creates the following tables:
+
+- `threads`: Stores conversation threads
+- `messages`: Stores individual messages
+- `metadata`: Stores additional metadata for threads and messages
+
+### Consistency & Propagation
+
+Cloudflare KV is an eventually consistent store, meaning that data may not be immediately available across all regions after a write.
+
+### Key Structure & Namespacing
+
+Keys in Cloudflare KV are structured as a combination of a configurable prefix and a table-specific format (e.g., `threads:threadId`).
+For Workers deployments, `keyPrefix` is used to isolate data within a namespace; for REST API deployments, `namespacePrefix` is used to isolate entire namespaces between environments or applications.

package/dist/index.cjs

@@ -620,21 +620,23 @@ var MemoryStorageCloudflare = class extends storage.MemoryStorage {
       return null;
     }
   }
-  async listThreadsByResourceId(args) {
+  async listThreads(args) {
+    const { page = 0, perPage: perPageInput, orderBy, filter } = args;
+    try {
+      this.validatePaginationInput(page, perPageInput ?? 100);
+    } catch (error$1) {
+      throw new error.MastraError(
+        {
+          id: storage.createStorageErrorId("CLOUDFLARE", "LIST_THREADS", "INVALID_PAGE"),
+          domain: error.ErrorDomain.STORAGE,
+          category: error.ErrorCategory.USER,
+          details: { page, ...perPageInput !== void 0 && { perPage: perPageInput } }
+        },
+        error$1 instanceof Error ? error$1 : new Error("Invalid pagination parameters")
+      );
+    }
+    const perPage = storage.normalizePerPage(perPageInput, 100);
     try {
-      const { resourceId, page = 0, perPage: perPageInput, orderBy } = args;
-      const perPage = storage.normalizePerPage(perPageInput, 100);
-      if (page < 0) {
-        throw new error.MastraError(
-          {
-            id: storage.createStorageErrorId("CLOUDFLARE", "LIST_THREADS_BY_RESOURCE_ID", "INVALID_PAGE"),
-            domain: error.ErrorDomain.STORAGE,
-            category: error.ErrorCategory.USER,
-            details: { page }
-          },
-          new Error("page must be >= 0")
-        );
-      }
       const { offset, perPage: perPageForResponse } = storage.calculatePagination(page, perPageInput, perPage);
       const { field, direction } = this.parseOrderBy(orderBy);
       const prefix = this.#db.namespacePrefix ? `${this.#db.namespacePrefix}:` : "";
@@ -643,7 +645,15 @@ var MemoryStorageCloudflare = class extends storage.MemoryStorage {
       for (const { name: key } of keyObjs) {
         const data = await this.#db.getKV(storage.TABLE_THREADS, key);
         if (!data) continue;
-        if (data.resourceId !== resourceId) continue;
+        if (filter?.resourceId && data.resourceId !== filter.resourceId) {
+          continue;
+        }
+        if (filter?.metadata && Object.keys(filter.metadata).length > 0) {
+          const metadata = this.ensureMetadata(data.metadata);
+          if (!metadata) continue;
+          const matches = Object.entries(filter.metadata).every(([key2, value]) => metadata[key2] === value);
+          if (!matches) continue;
+        }
         threads.push(data);
       }
       threads.sort((a, b) => {
@@ -663,10 +673,10 @@ var MemoryStorageCloudflare = class extends storage.MemoryStorage {
     } catch (error$1) {
       throw new error.MastraError(
         {
-          id: storage.createStorageErrorId("CLOUDFLARE", "LIST_THREADS_BY_RESOURCE_ID", "FAILED"),
+          id: storage.createStorageErrorId("CLOUDFLARE", "LIST_THREADS", "FAILED"),
           domain: error.ErrorDomain.STORAGE,
           category: error.ErrorCategory.THIRD_PARTY,
-          text: "Failed to get threads by resource ID with pagination"
+          text: "Failed to list threads with filters"
         },
         error$1
       );
@@ -1200,15 +1210,11 @@ var MemoryStorageCloudflare = class extends storage.MemoryStorage {
       if (resourceId) {
         filteredThreadMessages = filteredThreadMessages.filter((msg) => msg.resourceId === resourceId);
       }
-      const dateRange = filter?.dateRange;
-      if (dateRange) {
-        filteredThreadMessages = filteredThreadMessages.filter((msg) => {
-          const messageDate = new Date(msg.createdAt);
-          if (dateRange.start && messageDate < new Date(dateRange.start)) return false;
-          if (dateRange.end && messageDate > new Date(dateRange.end)) return false;
-          return true;
-        });
-      }
+      filteredThreadMessages = storage.filterByDateRange(
+        filteredThreadMessages,
+        (msg) => new Date(msg.createdAt),
+        filter?.dateRange
+      );
       const total = filteredThreadMessages.length;
       if (perPage === 0 && (!include || include.length === 0)) {
         return {
@@ -1989,7 +1995,7 @@ var WorkflowsStorageCloudflare = class extends storage.WorkflowsStorage {
       try {
         parsedSnapshot = JSON.parse(row.snapshot);
       } catch (e) {
-        console.warn(`Failed to parse snapshot for workflow ${row.workflow_name}: ${e}`);
+        this.logger.warn(`Failed to parse snapshot for workflow ${row.workflow_name}: ${e}`);
       }
     }
     return {
@@ -2163,7 +2169,7 @@ function isWorkersConfig(config) {
 }
 
 // src/storage/index.ts
-var CloudflareStore = class extends storage.MastraStorage {
+var CloudflareStore = class extends storage.MastraCompositeStore {
   stores;
   client;
   accountId;