@mastra/cloudflare 0.0.0-bundle-recursion-20251030002519 → 0.0.0-bundle-version-20260121091645
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +1508 -3
- package/README.md +38 -16
- package/dist/docs/README.md +31 -0
- package/dist/docs/SKILL.md +32 -0
- package/dist/docs/SOURCE_MAP.json +6 -0
- package/dist/docs/storage/01-reference.md +64 -0
- package/dist/index.cjs +1505 -1620
- package/dist/index.cjs.map +1 -1
- package/dist/index.js +1465 -1583
- package/dist/index.js.map +1 -1
- package/dist/storage/{domains/operations → db}/index.d.ts +22 -26
- package/dist/storage/db/index.d.ts.map +1 -0
- package/dist/storage/domains/memory/index.d.ts +60 -41
- package/dist/storage/domains/memory/index.d.ts.map +1 -1
- package/dist/storage/domains/scores/index.d.ts +16 -28
- package/dist/storage/domains/scores/index.d.ts.map +1 -1
- package/dist/storage/domains/workflows/index.d.ts +15 -22
- package/dist/storage/domains/workflows/index.d.ts.map +1 -1
- package/dist/storage/index.d.ts +27 -204
- package/dist/storage/index.d.ts.map +1 -1
- package/dist/storage/test-utils.d.ts.map +1 -1
- package/dist/storage/types.d.ts +68 -8
- package/dist/storage/types.d.ts.map +1 -1
- package/package.json +18 -13
- package/dist/storage/domains/legacy-evals/index.d.ts +0 -21
- package/dist/storage/domains/legacy-evals/index.d.ts.map +0 -1
- package/dist/storage/domains/operations/index.d.ts.map +0 -1
package/README.md
CHANGED
|
@@ -11,7 +11,7 @@ npm install @mastra/cloudflare
|
|
|
11
11
|
## Prerequisites
|
|
12
12
|
|
|
13
13
|
- Cloudflare account with KV namespaces set up
|
|
14
|
-
- Node.js
|
|
14
|
+
- Node.js 22.13.0 or later
|
|
15
15
|
- (Optional) Cloudflare Worker for Workers API mode
|
|
16
16
|
|
|
17
17
|
## Usage
|
|
@@ -25,7 +25,6 @@ const store = new CloudflareStore({
|
|
|
25
25
|
threads: THREADS_KV_NAMESPACE,
|
|
26
26
|
messages: MESSAGES_KV_NAMESPACE,
|
|
27
27
|
workflow_snapshot: WORKFLOW_KV_NAMESPACE,
|
|
28
|
-
evals: EVALS_KV_NAMESPACE,
|
|
29
28
|
traces: TRACES_KV_NAMESPACE,
|
|
30
29
|
},
|
|
31
30
|
keyPrefix: 'myapp_', // Optional
|
|
@@ -40,12 +39,13 @@ const store = new CloudflareStore({
|
|
|
40
39
|
|
|
41
40
|
// Save a thread
|
|
42
41
|
await store.saveThread({
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
42
|
+
thread: {
|
|
43
|
+
id: 'thread-123',
|
|
44
|
+
resourceId: 'resource-456',
|
|
45
|
+
title: 'My Thread',
|
|
46
|
+
metadata: { key: 'value' },
|
|
47
|
+
createdAt: new Date(),
|
|
48
|
+
},
|
|
49
49
|
});
|
|
50
50
|
|
|
51
51
|
// Add messages
|
|
@@ -62,7 +62,7 @@ await store.saveMessages({
|
|
|
62
62
|
});
|
|
63
63
|
|
|
64
64
|
// Query messages
|
|
65
|
-
const messages = await store.
|
|
65
|
+
const messages = await store.listMessages({ threadId: 'thread-123' });
|
|
66
66
|
```
|
|
67
67
|
|
|
68
68
|
## Configuration
|
|
@@ -95,25 +95,47 @@ const messages = await store.getMessages({ threadId: 'thread-123' });
|
|
|
95
95
|
|
|
96
96
|
### Thread Operations
|
|
97
97
|
|
|
98
|
-
- `saveThread(thread)`: Create or update a thread
|
|
98
|
+
- `saveThread({ thread })`: Create or update a thread
|
|
99
99
|
- `getThreadById({ threadId })`: Get a thread by ID
|
|
100
|
-
- `
|
|
100
|
+
- `listThreadsByResourceId({ resourceId, offset, limit, orderBy? })`: List paginated threads for a resource
|
|
101
101
|
- `updateThread({ id, title, metadata })`: Update thread title and metadata
|
|
102
102
|
- `deleteThread({ threadId })`: Delete a thread and its messages
|
|
103
103
|
|
|
104
104
|
### Message Operations
|
|
105
105
|
|
|
106
106
|
- `saveMessages({ messages })`: Save multiple messages
|
|
107
|
-
- `
|
|
107
|
+
- `listMessages({ threadId, perPage?, page? })`: Get messages for a thread with pagination
|
|
108
|
+
- `listMessagesById({ messageIds })`: Get specific messages by their IDs
|
|
109
|
+
- `updateMessages({ messages })`: Update existing messages
|
|
110
|
+
|
|
111
|
+
### Resource Operations
|
|
112
|
+
|
|
113
|
+
- `getResourceById({ resourceId })`: Get a resource by ID
|
|
114
|
+
- `saveResource({ resource })`: Create or save a resource
|
|
115
|
+
- `updateResource({ resourceId, workingMemory })`: Update resource working memory
|
|
108
116
|
|
|
109
117
|
### Workflow Operations
|
|
110
118
|
|
|
111
|
-
- `persistWorkflowSnapshot({ workflowName, runId, snapshot })`: Save workflow state
|
|
112
|
-
- `loadWorkflowSnapshot({ workflowName, runId })`: Load
|
|
119
|
+
- `persistWorkflowSnapshot({ workflowName, runId, snapshot })`: Save workflow state
|
|
120
|
+
- `loadWorkflowSnapshot({ workflowName, runId })`: Load workflow state
|
|
121
|
+
- `listWorkflowRuns({ workflowName, pagination })`: List workflow runs with pagination
|
|
122
|
+
- `getWorkflowRunById({ workflowName, runId })`: Get a specific workflow run
|
|
123
|
+
- `updateWorkflowState({ workflowName, runId, state })`: Update workflow state
|
|
124
|
+
- `updateWorkflowResults({ workflowName, runId, results })`: Update workflow results
|
|
125
|
+
|
|
126
|
+
### Evaluation/Scoring Operations
|
|
127
|
+
|
|
128
|
+
- `getScoreById({ id })`: Get a score by ID
|
|
129
|
+
- `saveScore(score)`: Save an evaluation score
|
|
130
|
+
- `listScoresByScorerId({ scorerId, pagination })`: List scores by scorer with pagination
|
|
131
|
+
- `listScoresByRunId({ runId, pagination })`: List scores by run with pagination
|
|
132
|
+
- `listScoresByEntityId({ entityId, entityType, pagination })`: List scores by entity with pagination
|
|
133
|
+
- `listScoresBySpan({ traceId, spanId, pagination })`: List scores by span with pagination
|
|
113
134
|
|
|
114
|
-
###
|
|
135
|
+
### Operations Not Currently Supported
|
|
115
136
|
|
|
116
|
-
- `
|
|
137
|
+
- `deleteMessages(messageIds)`: Message deletion is not currently supported
|
|
138
|
+
- AI Observability (traces/spans): Not currently supported
|
|
117
139
|
|
|
118
140
|
### Utility
|
|
119
141
|
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
# @mastra/cloudflare Documentation
|
|
2
|
+
|
|
3
|
+
> Embedded documentation for coding agents
|
|
4
|
+
|
|
5
|
+
## Quick Start
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
# Read the skill overview
|
|
9
|
+
cat docs/SKILL.md
|
|
10
|
+
|
|
11
|
+
# Get the source map
|
|
12
|
+
cat docs/SOURCE_MAP.json
|
|
13
|
+
|
|
14
|
+
# Read topic documentation
|
|
15
|
+
cat docs/<topic>/01-overview.md
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
## Structure
|
|
19
|
+
|
|
20
|
+
```
|
|
21
|
+
docs/
|
|
22
|
+
├── SKILL.md # Entry point
|
|
23
|
+
├── README.md # This file
|
|
24
|
+
├── SOURCE_MAP.json # Export index
|
|
25
|
+
├── storage/ (1 files)
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
## Version
|
|
29
|
+
|
|
30
|
+
Package: @mastra/cloudflare
|
|
31
|
+
Version: 1.0.0
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: mastra-cloudflare-docs
|
|
3
|
+
description: Documentation for @mastra/cloudflare. Includes links to type definitions and readable implementation code in dist/.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# @mastra/cloudflare Documentation
|
|
7
|
+
|
|
8
|
+
> **Version**: 1.0.0
|
|
9
|
+
> **Package**: @mastra/cloudflare
|
|
10
|
+
|
|
11
|
+
## Quick Navigation
|
|
12
|
+
|
|
13
|
+
Use SOURCE_MAP.json to find any export:
|
|
14
|
+
|
|
15
|
+
```bash
|
|
16
|
+
cat docs/SOURCE_MAP.json
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
Each export maps to:
|
|
20
|
+
- **types**: `.d.ts` file with JSDoc and API signatures
|
|
21
|
+
- **implementation**: `.js` chunk file with readable source
|
|
22
|
+
- **docs**: Conceptual documentation in `docs/`
|
|
23
|
+
|
|
24
|
+
## Top Exports
|
|
25
|
+
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
See SOURCE_MAP.json for the complete list.
|
|
29
|
+
|
|
30
|
+
## Available Topics
|
|
31
|
+
|
|
32
|
+
- [Storage](storage/) - 1 file(s)
|
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
# Storage API Reference
|
|
2
|
+
|
|
3
|
+
> API reference for storage - 1 entries
|
|
4
|
+
|
|
5
|
+
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
## Reference: Cloudflare Storage
|
|
9
|
+
|
|
10
|
+
> Documentation for the Cloudflare KV storage implementation in Mastra.
|
|
11
|
+
|
|
12
|
+
The Cloudflare KV storage implementation provides a globally distributed, serverless key-value store solution using Cloudflare Workers KV.
|
|
13
|
+
|
|
14
|
+
## Installation
|
|
15
|
+
|
|
16
|
+
```bash
|
|
17
|
+
npm install @mastra/cloudflare@latest
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
## Usage
|
|
21
|
+
|
|
22
|
+
```typescript
|
|
23
|
+
import { CloudflareStore } from "@mastra/cloudflare";
|
|
24
|
+
|
|
25
|
+
// --- Example 1: Using Workers Binding ---
|
|
26
|
+
const storageWorkers = new CloudflareStore({
|
|
27
|
+
id: "cloudflare-workers-storage",
|
|
28
|
+
bindings: {
|
|
29
|
+
threads: THREADS_KV, // KVNamespace binding for threads table
|
|
30
|
+
messages: MESSAGES_KV, // KVNamespace binding for messages table
|
|
31
|
+
// Add other tables as needed
|
|
32
|
+
},
|
|
33
|
+
keyPrefix: "dev_", // Optional: isolate keys per environment
|
|
34
|
+
});
|
|
35
|
+
|
|
36
|
+
// --- Example 2: Using REST API ---
|
|
37
|
+
const storageRest = new CloudflareStore({
|
|
38
|
+
id: "cloudflare-rest-storage",
|
|
39
|
+
accountId: process.env.CLOUDFLARE_ACCOUNT_ID!, // Cloudflare Account ID
|
|
40
|
+
apiToken: process.env.CLOUDFLARE_API_TOKEN!, // Cloudflare API Token
|
|
41
|
+
namespacePrefix: "dev_", // Optional: isolate namespaces per environment
|
|
42
|
+
});
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
## Parameters
|
|
46
|
+
|
|
47
|
+
#### Additional Notes
|
|
48
|
+
|
|
49
|
+
### Schema Management
|
|
50
|
+
|
|
51
|
+
The storage implementation handles schema creation and updates automatically. It creates the following tables:
|
|
52
|
+
|
|
53
|
+
- `threads`: Stores conversation threads
|
|
54
|
+
- `messages`: Stores individual messages
|
|
55
|
+
- `metadata`: Stores additional metadata for threads and messages
|
|
56
|
+
|
|
57
|
+
### Consistency & Propagation
|
|
58
|
+
|
|
59
|
+
Cloudflare KV is an eventually consistent store, meaning that data may not be immediately available across all regions after a write.
|
|
60
|
+
|
|
61
|
+
### Key Structure & Namespacing
|
|
62
|
+
|
|
63
|
+
Keys in Cloudflare KV are structured as a combination of a configurable prefix and a table-specific format (e.g., `threads:threadId`).
|
|
64
|
+
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.
|