{"_id":"@askelephant/mastra-firestore","_rev":"7-9f71df8f8d96051cdc8308aedc877ba9","name":"@askelephant/mastra-firestore","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@askelephant/mastra-firestore","version":"0.1.0","keywords":["mastra"],"author":{"name":"kdawgwilk"},"license":"MIT","_id":"@askelephant/mastra-firestore@0.1.0","maintainers":[{"name":"kdawgwilk-elephant","email":"kaden@askelephant.ai"},{"name":"kdawgwilk","email":"wilkinson.kaden@gmail.com"}],"homepage":"https://github.com/AskElephant/mastra-firestore#readme","bugs":{"url":"https://github.com/AskElephant/mastra-firestore/issues"},"dist":{"shasum":"c78b05e279bde05a77ace98d6043e579ba70ce79","tarball":"https://registry.npmjs.org/@askelephant/mastra-firestore/-/mastra-firestore-0.1.0.tgz","fileCount":50,"integrity":"sha512-rOYCLCsuxKx5StGJCG6PLKSEYSdEQ7l/b4iXGGHEsQjGs4lx8VczJULB7do6y9ZDmvZrcQOn3znZAG5iCwkwJQ==","signatures":[{"sig":"MEUCIBKDJ6G4zhjjNuNSdcR4RzW9DVPSlPqV5VjsJtTOkJu7AiEA92xha0k7eFcThwo1kzpgc2rKlKNsuj90s0pxOeRQW3E=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":142659},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","gitHead":"e661da3f637748670a7ba126cbc4699fa43641a8","scripts":{"lint":"npx @biomejs/biome check --write","test":"vitest","build":"tsc","lint:ci":"npx @biomejs/biome check","publish":"npm publish --access public","prepublishOnly":"npm run lint:ci"},"_npmUser":{"name":"kdawgwilk-elephant","email":"kaden@askelephant.ai"},"repository":{"url":"git+https://github.com/AskElephant/mastra-firestore.git","type":"git"},"_npmVersion":"10.9.2","description":"Mastra storage plugin for Firestore","directories":{},"_nodeVersion":"22.14.0","dependencies":{"@mastra/core":"^0.21.1"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^3.2.4","typescript":"^5.9.3","@biomejs/biome":"2.2.6"},"peerDependencies":{"firebase-admin":"12.x.x || 13.x.x"},"_npmOperationalInternal":{"tmp":"tmp/mastra-firestore_0.1.0_1760866346611_0.19186036225251835","host":"s3://npm-registry-packages-npm-production"}}},"time":{"created":"2025-10-19T09:32:26.546Z","modified":"2026-08-26T21:52:06.240Z","0.1.0":"2025-10-19T09:32:26.815Z"},"bugs":{"url":"https://github.com/AskElephant/mastra-firestore/issues"},"author":{"name":"kdawgwilk"},"license":"MIT","homepage":"https://github.com/AskElephant/mastra-firestore#readme","keywords":["mastra"],"repository":{"url":"git+https://github.com/AskElephant/mastra-firestore.git","type":"git"},"description":"Mastra storage plugin for Firestore","maintainers":[{"email":"kaden@askelephant.ai","name":"kdawgwilk-elephant"},{"email":"bryan@askelephant.ai","name":"bryan.lund"}],"readme":"# Mastra Firestore Storage Plugin\n\n[![npm version](https://badge.fury.io/js/@askelephant%2Fmastra-firestore.svg)](https://www.npmjs.com/package/@askelephant/mastra-firestore)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\nA Firestore storage adapter for the [Mastra AI framework](https://mastra.ai), providing persistent storage for agents, workflows, memory, and observability.\n\n## Features\n\n- 🔥 **Firebase/Firestore Integration** - Leverage Google Cloud Firestore for scalable, real-time storage\n- 🧠 **Memory Management** - Persistent storage for threads, messages, and agent memory\n- 🔄 **Workflow State** - Save and restore workflow execution states\n- 📊 **Observability** - Store and query AI traces and spans for monitoring\n- 📈 **Scoring & Evals** - Track evaluation results and scores\n- 🔍 **Advanced Queries** - Paginated queries with filtering and sorting\n- ⚡ **Batch Operations** - Efficient batch inserts and updates\n\n## Installation\n\n```bash\nnpm install @askelephant/mastra-firestore firebase-admin\n```\n\n## Usage\n\n### Basic Setup\n\n```typescript\nimport { FirestoreStore } from \"@askelephant/mastra-firestore\";\nimport { initializeApp, cert } from \"firebase-admin/app\";\nimport { getFirestore } from \"firebase-admin/firestore\";\nimport { Mastra } from \"@mastra/core\";\n\n// Initialize Firebase Admin\nconst app = initializeApp();\n\nconst db = getFirestore(app);\n\n// Create the Firestore storage instance\nconst storage = new FirestoreStore({ db });\n\n// Use with Mastra\nconst mastra = new Mastra({\n  storage,\n  // ... other configuration\n});\n```\n\n## Supported Features\n\nThe Firestore storage plugin supports all major Mastra storage features:\n\n```typescript\nstorage.supports = {\n  selectByIncludeResourceScope: true,\n  resourceWorkingMemory: true,\n  hasColumn: true,\n  createTable: true,\n  deleteMessages: true,\n  aiTracing: true,\n  getScoresBySpan: true,\n};\n```\n\n## API Overview\n\n### Memory & Threads\n\n```typescript\n// Save and retrieve threads\nconst thread = await storage.saveThread({\n  thread: {\n    id: \"thread-123\",\n    resourceId: \"user-456\",\n    title: \"Customer Support Chat\",\n    metadata: { channel: \"web\" },\n  },\n});\n\n// Get threads by resource with pagination\nconst { threads, ...pagination } =\n  await storage.getThreadsByResourceIdPaginated({\n    resourceId: \"user-456\",\n    page: 1,\n    perPage: 10,\n  });\n\n// Save messages to a thread\nawait storage.saveMessages({\n  messages: [\n    {\n      id: \"msg-1\",\n      threadId: \"thread-123\",\n      role: \"user\",\n      content: { content: \"Hello!\", metadata: {} },\n      createdAt: new Date(),\n    },\n  ],\n  format: \"v2\",\n});\n\n// Get messages with pagination\nconst { messages, ...paginationInfo } = await storage.getMessagesPaginated({\n  threadId: \"thread-123\",\n  pagination: { page: 1, perPage: 20 },\n});\n```\n\n### Workflows\n\n```typescript\n// Persist workflow state\nawait storage.persistWorkflowSnapshot({\n  workflowName: \"customer-onboarding\",\n  runId: \"run-123\",\n  resourceId: \"user-456\",\n  snapshot: {\n    status: \"running\",\n    results: {},\n    error: null,\n    // ... workflow state\n  },\n});\n\n// Load workflow state\nconst state = await storage.loadWorkflowSnapshot({\n  workflowName: \"customer-onboarding\",\n  runId: \"run-123\",\n});\n\n// Query workflow runs\nconst runs = await storage.getWorkflowRuns({\n  workflowName: \"customer-onboarding\",\n  fromDate: new Date(\"2024-01-01\"),\n  limit: 10,\n});\n```\n\n### Observability & Tracing\n\n```typescript\n// Create AI span for observability\nawait storage.createAISpan({\n  spanId: \"span-123\",\n  traceId: \"trace-456\",\n  name: \"llm.completion\",\n  startTime: Date.now(),\n  attributes: {\n    model: \"gpt-4\",\n    tokens: 150,\n  },\n});\n\n// Get traces with pagination\nconst { spans, pagination } = await storage.getAITracesPaginated({\n  filters: { model: \"gpt-4\" },\n  pagination: { page: 1, perPage: 50 },\n});\n\n// Get specific trace\nconst trace = await storage.getAITrace(\"trace-456\");\n```\n\n### Scoring & Evaluation\n\n```typescript\n// Save evaluation score\nconst { score } = await storage.saveScore({\n  scorerId: \"quality-scorer\",\n  runId: \"run-123\",\n  entityType: \"message\",\n  entityId: \"msg-456\",\n  value: 0.95,\n  metadata: { criteria: \"helpfulness\" },\n});\n\n// Get scores by scorer\nconst { scores, pagination } = await storage.getScoresByScorerId({\n  scorerId: \"quality-scorer\",\n  pagination: { page: 1, perPage: 10 },\n});\n\n// Get scores for specific span\nconst spanScores = await storage.getScoresBySpan({\n  traceId: \"trace-456\",\n  spanId: \"span-123\",\n  pagination: { page: 1, perPage: 10 },\n});\n```\n\n### Generic Operations\n\n```typescript\n// Create table/collection\nawait storage.createTable({\n  tableName: \"custom_data\",\n  schema: {\n    id: { type: \"string\", primaryKey: true },\n    data: { type: \"json\" },\n  },\n});\n\n// Insert record\nawait storage.insert({\n  tableName: \"custom_data\",\n  record: { id: \"123\", data: { key: \"value\" } },\n});\n\n// Batch insert\nawait storage.batchInsert({\n  tableName: \"custom_data\",\n  records: [\n    { id: \"1\", data: { foo: \"bar\" } },\n    { id: \"2\", data: { baz: \"qux\" } },\n  ],\n});\n\n// Load record\nconst record = await storage.load({\n  tableName: \"custom_data\",\n  keys: { id: \"123\" },\n});\n```\n\n## Firestore Collections\n\nThe plugin uses the following Firestore collections:\n\n- `threads` - Conversation threads\n- `messages` - Thread messages\n- `resources` - Resource metadata and working memory\n- `workflows` - Workflow execution states\n- `traces` - OpenTelemetry traces\n- `ai_spans` - AI operation spans for observability\n- `scores` - Evaluation scores\n- `evals` - Legacy evaluation results\n\n## Development\n\n### Prerequisites\n\n- Node.js >= 22\n- Firebase Admin SDK credentials\n- npm\n\n### Setup\n\n```bash\n# Clone the repository\ngit clone https://github.com/AskElephant/mastra-firestore.git\ncd mastra-firestore\n\n# Install dependencies\nnpm install\n\n# Build the project\nnpm run build\n\n# Run tests\nnpm test\n\n# Lint code\nnpm run lint\n```\n\n### Running Tests\n\nTests use Vitest and require a Firebase project configured:\n\n```bash\n# Create .env.test with your test Firebase credentials\nnpm test\n```\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add some amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Links\n\n- [Mastra Documentation](https://mastra.ai/docs)\n- [Firebase Admin SDK](https://firebase.google.com/docs/admin/setup)\n- [GitHub Repository](https://github.com/AskElephant/mastra-firestore)\n- [npm Package](https://www.npmjs.com/package/@askelephant/mastra-firestore)\n- [Issue Tracker](https://github.com/AskElephant/mastra-firestore/issues)\n\n## Support\n\nFor issues and questions:\n\n- Open an issue on [GitHub](https://github.com/AskElephant/mastra-firestore/issues)\n- Check the [Mastra documentation](https://mastra.ai/docs)\n- Review [Firebase documentation](https://firebase.google.com/docs)\n\n## Author\n\n[kdawgwilk](https://github.com/kdawgwilk)\n\n---\n\nMade with ❤️ by [AskElephant](https://askelephant.ai) for the Mastra community\n","readmeFilename":"README.md"}