@mastra/cloudflare 0.0.0-error-handler-fix-20251020202607 → 0.0.0-execa-dynamic-import-20260304221256

package/LICENSE.md

@@ -1,3 +1,18 @@
+Portions of this software are licensed as follows:
+
+- All content that resides under any directory named "ee/" within this
+  repository, including but not limited to:
+  - `packages/core/src/auth/ee/`
+  - `packages/server/src/server/auth/ee/`
+    is licensed under the license defined in `ee/LICENSE`.
+
+- All third-party components incorporated into the Mastra Software are
+  licensed under the original license provided by the owner of the
+  applicable component.
+
+- Content outside of the above-mentioned directories or restrictions is
+  available under the "Apache License 2.0" as defined below.
+
 # Apache License 2.0
 
 Copyright (c) 2025 Kepler Software, Inc.

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
@@ -25,7 +25,6 @@ const store = new CloudflareStore({
     threads: THREADS_KV_NAMESPACE,
     messages: MESSAGES_KV_NAMESPACE,
     workflow_snapshot: WORKFLOW_KV_NAMESPACE,
-    evals: EVALS_KV_NAMESPACE,
     traces: TRACES_KV_NAMESPACE,
   },
   keyPrefix: 'myapp_', // Optional
@@ -40,12 +39,13 @@ const store = new CloudflareStore({
 
 // Save a thread
 await store.saveThread({
-  id: 'thread-123',
-  resourceId: 'resource-456',
-  title: 'My Thread',
-  metadata: { key: 'value' },
-  createdAt: new Date(),
-  updatedAt: new Date(),
+  thread: {
+    id: 'thread-123',
+    resourceId: 'resource-456',
+    title: 'My Thread',
+    metadata: { key: 'value' },
+    createdAt: new Date(),
+  },
 });
 
 // Add messages
@@ -62,7 +62,7 @@ await store.saveMessages({
 });
 
 // Query messages
-const messages = await store.getMessages({ threadId: 'thread-123' });
+const messages = await store.listMessages({ threadId: 'thread-123' });
 ```
 
 ## Configuration
@@ -95,25 +95,47 @@ const messages = await store.getMessages({ threadId: 'thread-123' });
 
 ### Thread Operations
 
-- `saveThread(thread)`: Create or update a thread
+- `saveThread({ thread })`: Create or update a thread
 - `getThreadById({ threadId })`: Get a thread by ID
-- `getThreadsByResourceId({ resourceId })`: Fetch all threads associated with a resource.
+- `listThreadsByResourceId({ resourceId, offset, limit, orderBy? })`: List paginated threads for a resource
 - `updateThread({ id, title, metadata })`: Update thread title and metadata
 - `deleteThread({ threadId })`: Delete a thread and its messages
 
 ### Message Operations
 
 - `saveMessages({ messages })`: Save multiple messages
-- `getMessages({ threadId, selectBy? })`: Get messages for a thread with optional filtering (last N, includes, etc)
+- `listMessages({ threadId, perPage?, page? })`: Get messages for a thread with pagination
+- `listMessagesById({ messageIds })`: Get specific messages by their IDs
+- `updateMessages({ messages })`: Update existing messages
+
+### Resource Operations
+
+- `getResourceById({ resourceId })`: Get a resource by ID
+- `saveResource({ resource })`: Create or save a resource
+- `updateResource({ resourceId, workingMemory })`: Update resource working memory
 
 ### Workflow Operations
 
-- `persistWorkflowSnapshot({ workflowName, runId, snapshot })`: Save workflow state for a given workflow/run.
-- `loadWorkflowSnapshot({ workflowName, runId })`: Load ed workflow state.
+- `persistWorkflowSnapshot({ workflowName, runId, snapshot })`: Save workflow state
+- `loadWorkflowSnapshot({ workflowName, runId })`: Load workflow state
+- `listWorkflowRuns({ workflowName, pagination })`: List workflow runs with pagination
+- `getWorkflowRunById({ workflowName, runId })`: Get a specific workflow run
+- `updateWorkflowState({ workflowName, runId, state })`: Update workflow state
+- `updateWorkflowResults({ workflowName, runId, results })`: Update workflow results
+
+### Evaluation/Scoring Operations
+
+- `getScoreById({ id })`: Get a score by ID
+- `saveScore(score)`: Save an evaluation score
+- `listScoresByScorerId({ scorerId, pagination })`: List scores by scorer with pagination
+- `listScoresByRunId({ runId, pagination })`: List scores by run with pagination
+- `listScoresByEntityId({ entityId, entityType, pagination })`: List scores by entity with pagination
+- `listScoresBySpan({ traceId, spanId, pagination })`: List scores by span with pagination
 
-### Trace Operations
+### Operations Not Currently Supported
 
-- `getTraces({ name?, scope?, page, perPage, attributes? })`: Query trace records with optional filters and pagination.
+- `deleteMessages(messageIds)`: Message deletion is not currently supported
+- AI Observability (traces/spans): Not currently supported
 
 ### Utility
 

package/dist/docs/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: mastra-cloudflare
+description: Documentation for @mastra/cloudflare. Use when working with @mastra/cloudflare APIs, configuration, or implementation.
+metadata:
+  package: "@mastra/cloudflare"
+  version: "0.0.0-execa-dynamic-import-20260304221256"
+---
+
+## When to use
+
+Use this skill whenever you are working with @mastra/cloudflare to obtain the domain-specific knowledge.
+
+## How to use
+
+Read the individual reference documents for detailed explanations and code examples.
+
+### Reference
+
+- [Reference: Cloudflare Storage](references/reference-storage-cloudflare.md) - Documentation for the Cloudflare KV storage implementation in Mastra.
+
+
+Read [assets/SOURCE_MAP.json](assets/SOURCE_MAP.json) for source code references.

package/dist/docs/assets/SOURCE_MAP.json

@@ -0,0 +1,6 @@
+{
+  "version": "0.0.0-execa-dynamic-import-20260304221256",
+  "package": "@mastra/cloudflare",
+  "exports": {},
+  "modules": {}
+}

package/dist/docs/references/reference-storage-cloudflare.md

@@ -0,0 +1,88 @@
+# Cloudflare Storage
+
+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) to route observability data to a supported provider like ClickHouse or PostgreSQL.
+
+## Installation
+
+**npm**:
+
+```bash
+npm install @mastra/cloudflare@latest
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/cloudflare@latest
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/cloudflare@latest
+```
+
+**Bun**:
+
+```bash
+bun add @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
+
+**id:** (`string`): Unique identifier for this storage instance.
+
+**bindings?:** (`Record<string, KVNamespace>`): Cloudflare Workers KV bindings (for Workers runtime)
+
+**accountId?:** (`string`): Cloudflare Account ID (for REST API)
+
+**apiToken?:** (`string`): Cloudflare API Token (for REST API)
+
+**namespacePrefix?:** (`string`): Optional prefix for all namespace names (useful for environment isolation)
+
+**keyPrefix?:** (`string`): Optional prefix for all keys (useful for environment isolation)
+
+### 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.