{"_id":"@elizaos/plugin-s3-storage-root","_rev":"4-8b28e743271455d61864a0d70f24163c","name":"@elizaos/plugin-s3-storage-root","dist-tags":{"next":"2.0.0-alpha.1","latest":"2.0.0-alpha.1"},"versions":{"2.0.0-alpha.1":{"name":"@elizaos/plugin-s3-storage-root","version":"2.0.0-alpha.1","keywords":[],"author":{"name":"elizaOS"},"license":"MIT","_id":"@elizaos/plugin-s3-storage-root@2.0.0-alpha.1","maintainers":[{"name":"shawticus","email":"shawmakesmagic@gmail.com"},{"name":"shakkernerd","email":"shakkerdroid@gmail.com"},{"name":"wtfsayo","email":"hi@sayo.wtf"},{"name":"odilitime","email":"janesmith@airmail.cc"},{"name":"cjft","email":"cjft@trimboli.io"}],"homepage":"https://github.com/elizaos-plugins/plugin-storage-s3#readme","bugs":{"url":"https://github.com/elizaos-plugins/plugin-storage-s3/issues"},"dist":{"shasum":"d85c8849acc8e44d654ce8fc8b150ae93b360925","tarball":"https://registry.npmjs.org/@elizaos/plugin-s3-storage-root/-/plugin-s3-storage-root-2.0.0-alpha.1.tgz","fileCount":69,"integrity":"sha512-rtcx2VOjPSH+DBtw48oTeBnrZsbab41ExltvW1QzdsbCODpoj9lXs6akuI1QSbJerQS+OduyA7Dv8l7KtAol1w==","signatures":[{"sig":"MEUCIF3hMTF7zLjIrpIH8tONL4u7I+RqO+wjW30XEZZi4wNlAiEA/WdpZiTjwU1TSUJ/db6Z8xkhrJ8n58uGam282UGC9dw=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":3130137},"main":"typescript/dist/index.js","type":"module","types":"typescript/dist/index.d.ts","exports":{".":{"types":"./typescript/dist/index.d.ts","import":"./typescript/dist/index.js","default":"./typescript/dist/index.js"},"./rust":{"import":"./rust/pkg/node/elizaos_plugin_plugin_s3_storage.js"},"./package.json":"./package.json"},"gitHead":"05d4ca11d769db8c7f54a722ee24b2ce2b951543","scripts":{"dev":"cd typescript && bun --hot build.ts","lint":"bunx @biomejs/biome check --write ./typescript","test":"bun run test:ts && bun run test:rust && bun run test:python","build":"bun run build:ts && bun run build:rust && bun run build:python","clean":"rm -rf typescript/dist python/dist rust/target .turbo node_modules","test:ts":"cd typescript && vitest run || echo 'TypeScript tests skipped - no tests found'","build:ts":"cd typescript && bun run build.ts","lint:rust":"test -d rust && cd rust && cargo clippy --all-targets --fix --allow-dirty --allow-staged -- -D warnings && cargo fmt || echo 'Rust lint skipped'","test:rust":"test -d rust && cd rust && cargo test || echo 'Rust tests skipped'","typecheck":"tsc --noEmit -p typescript/tsconfig.json","build:rust":"test -d rust && cd rust && cargo build --release || echo 'Rust build skipped - no rust directory'","lint:check":"bunx @biomejs/biome check ./typescript","lint:python":"test -d python && cd python && ruff check --fix . && ruff format . || echo 'Python lint skipped'","test:python":"test -d python && cd python && pip install -e '.[dev]' --quiet && pytest -p no:anchorpy --asyncio-mode=auto || echo 'Python tests skipped'","build:python":"test -d python && cd python && (python3 -m build 2>/dev/null || pyproject-build) || echo 'Python build skipped - no python directory'","lint:python:fix":"test -d python && cd python && ruff check --fix . && ruff format . || echo 'Python lint fix skipped'"},"_npmUser":{"name":"shawticus","email":"shawmakesmagic@gmail.com"},"repository":{"url":"git+https://github.com/elizaos-plugins/plugin-storage-s3.git","type":"git"},"_npmVersion":"lerna/9.0.3/node@v22.20.0+arm64 (darwin)","agentConfig":{"pluginType":"elizaos:plugin:1.0.0","pluginParameters":{"AWS_REGION":{"type":"string","required":true,"sensitive":false,"description":"AWS region in which the S3 bucket resides."},"AWS_S3_BUCKET":{"type":"string","required":true,"sensitive":false,"description":"Name of the AWS S3 bucket used for file uploads and downloads."},"AWS_S3_ENDPOINT":{"type":"string","required":false,"sensitive":false,"description":"Custom S3-compatible endpoint (e.g., for non-AWS providers)."},"AWS_ACCESS_KEY_ID":{"type":"string","required":true,"sensitive":true,"description":"AWS access key ID used for authenticating requests to AWS S3."},"AWS_S3_SSL_ENABLED":{"type":"boolean","required":false,"sensitive":false,"description":"Flag indicating whether SSL should be enabled for the custom S3 endpoint."},"AWS_S3_UPLOAD_PATH":{"type":"string","required":false,"sensitive":false,"description":"Default path or prefix inside the S3 bucket where files will be uploaded."},"AWS_SECRET_ACCESS_KEY":{"type":"string","required":true,"sensitive":true,"description":"AWS secret access key used for authenticating requests to AWS S3."},"AWS_S3_FORCE_PATH_STYLE":{"type":"boolean","required":false,"sensitive":false,"description":"Flag to force path-style addressing when connecting to the S3 endpoint."}}},"description":"Core Node.js plugin for Eliza OS that provides essential services and actions for file operations, media processing, and cloud integrations.","directories":{},"_nodeVersion":"22.20.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"@types/bun":"^1.3.5","typescript":"^5.9.3","@types/node":"^25.0.3","@biomejs/biome":"^2.3.11"},"peerDependencies":{"@elizaos/core":"2.0.0-alpha.1"},"_npmOperationalInternal":{"tmp":"tmp/plugin-s3-storage-root_2.0.0-alpha.1_1769034091331_0.5046718237087997","host":"s3://npm-registry-packages-npm-production"}}},"time":{"created":"2026-01-21T22:21:31.155Z","modified":"2026-06-16T05:15:06.314Z","2.0.0-alpha.1":"2026-01-21T22:21:31.481Z"},"bugs":{"url":"https://github.com/elizaos-plugins/plugin-storage-s3/issues"},"author":{"name":"elizaOS"},"license":"MIT","homepage":"https://github.com/elizaos-plugins/plugin-storage-s3#readme","keywords":[],"repository":{"url":"git+https://github.com/elizaos-plugins/plugin-storage-s3.git","type":"git"},"description":"Core Node.js plugin for Eliza OS that provides essential services and actions for file operations, media processing, and cloud integrations.","maintainers":[{"email":"shawmakesmagic@gmail.com","name":"shawticus"},{"email":"janesmith@airmail.cc","name":"odilitime"}],"readme":"# @elizaos/plugin-node\n\nCore Node.js plugin for Eliza OS that provides essential services and actions for file operations, media processing, and cloud integrations.\n\n## Overview\n\nThe Node plugin serves as a foundational component of Eliza OS, bridging core Node.js capabilities with the Eliza ecosystem. It provides crucial services for file operations, media processing, speech synthesis, and cloud integrations, enabling both local and cloud-based functionality for Eliza agents.\n\n## Features\n\n- **AWS S3 Integration**: File upload and management with AWS S3\n- **Browser Automation**: Web scraping and content extraction with Playwright\n- **Image Processing**: Image description and analysis capabilities\n- **PDF Processing**: PDF text extraction and parsing\n- **Speech Synthesis**: Text-to-speech using ElevenLabs and VITS\n- **Transcription**: Speech-to-text using various providers (OpenAI, Deepgram, Local)\n- **Video Processing**: YouTube video download and transcription\n- **LLaMA Integration**: Local LLM support with LLaMA models\n\n## Installation\n\n```bash\nnpm install @elizaos/plugin-node\n```\n\n## Configuration\n\nThe plugin requires various environment variables depending on which services you plan to use:\n\n### Core Settings\n\n```env\nOPENAI_API_KEY=your_openai_api_key\n```\n\n### Voice Settings (Optional)\n\n```env\nELEVENLABS_API_KEY=your_elevenlabs_api_key\nELEVENLABS_MODEL_ID=eleven_monolingual_v1\nELEVENLABS_VOICE_ID=your_voice_id\nELEVENLABS_VOICE_STABILITY=0.5\nELEVENLABS_VOICE_SIMILARITY_BOOST=0.75\nELEVENLABS_OPTIMIZE_STREAMING_LATENCY=0\nELEVENLABS_OUTPUT_FORMAT=pcm_16000\nVITS_VOICE=en_US-hfc_female-medium\n```\n\n### AWS Settings (Optional)\n\n```env\nAWS_ACCESS_KEY_ID=your_aws_access_key\nAWS_SECRET_ACCESS_KEY=your_aws_secret_key\nAWS_REGION=your_aws_region\nAWS_S3_BUCKET=your_s3_bucket\nAWS_S3_UPLOAD_PATH=your_upload_path\nAWS_S3_ENDPOINT=an_alternative_endpoint\nAWS_S3_SSL_ENABLED=boolean(true|false)\nAWS_S3_FORCE_PATH_STYLE=boolean(true|false)\n```\n\n## Usage\n\n```typescript\nimport { createNodePlugin } from \"@elizaos/plugin-node\";\n\n// Initialize the plugin\nconst nodePlugin = createNodePlugin();\n\n// Register with Eliza OS\nelizaos.registerPlugin(nodePlugin);\n```\n\n## Services\n\n### AwsS3Service\n\nHandles file uploads and management with AWS S3.\n\n### BrowserService\n\nProvides web scraping and content extraction capabilities using Playwright.\n\n### ImageDescriptionService\n\nProcesses and analyzes images to generate descriptions. Supports multiple providers:\n\n- Local processing using Florence model\n- OpenAI Vision API\n- Google Gemini\n\nConfiguration:\n\n```env\n# For OpenAI Vision\nOPENAI_API_KEY=your_openai_api_key\n\n# For Google Gemini\nGOOGLE_GENERATIVE_AI_API_KEY=your_google_api_key\n```\n\nProvider selection:\n\n- If `imageVisionModelProvider` is set to `google/openai`, it will use this one.\n- Else if `model` is set to `google/openai`, it will use this one.\n- Default if nothing is set is OpenAI.\n\nThe service automatically handles different image formats, including GIFs (first frame extraction).\n\nFeatures by provider:\n\n**Local (Florence):**\n\n- Basic image captioning\n- Local processing without API calls\n\n**OpenAI Vision:**\n\n- Detailed image descriptions\n- Text detection\n- Object recognition\n\n**Google Gemini 1.5:**\n\n- High-quality image understanding\n- Detailed descriptions with natural language\n- Multi-modal context understanding\n- Support for complex scenes and content\n\nThe provider can be configured through the runtime settings, allowing easy switching between providers based on your needs.\n\n### LlamaService\n\nProvides local LLM capabilities using LLaMA models.\n\n### PdfService\n\nExtracts and processes text content from PDF files.\n\n### SpeechService\n\nHandles text-to-speech conversion using ElevenLabs and VITS.\n\n### TranscriptionService\n\nConverts speech to text using various providers.\n\n### VideoService\n\nProcesses video content, including YouTube video downloads and transcription.\n\n## Actions\n\n### describeImage\n\nAnalyzes and generates descriptions for images.\n\n```typescript\n// Example usage\nconst result = await runtime.executeAction(\"DESCRIBE_IMAGE\", {\n  imageUrl: \"path/to/image.jpg\",\n});\n```\n\n## Dependencies\n\nThe plugin requires several peer dependencies:\n\n- `onnxruntime-node`: 1.20.1\n- `whatwg-url`: 7.1.0\n\nAnd trusted dependencies:\n\n- `onnxruntime-node`: 1.20.1\n- `sharp`: 0.33.5\n\n## Safety & Security\n\n### File Operations\n\n- **Path Sanitization**: All file paths are sanitized to prevent directory traversal attacks\n- **File Size Limits**: Enforced limits on upload sizes\n- **Type Checking**: Strict file type validation\n- **Temporary File Cleanup**: Automatic cleanup of temporary files\n\n### API Keys & Credentials\n\n- **Environment Isolation**: Sensitive credentials are isolated in environment variables\n- **Access Scoping**: Services are initialized with minimum required permissions\n- **Key Rotation**: Support for credential rotation without service interruption\n\n### Media Processing\n\n- **Resource Limits**: Memory and CPU usage limits for media processing\n- **Timeout Controls**: Automatic termination of long-running processes\n- **Format Validation**: Strict media format validation before processing\n\n## Troubleshooting\n\n### Common Issues\n\n1. **Service Initialization Failures**\n\n```bash\nError: Service initialization failed\n```\n\n- Verify environment variables are properly set\n- Check service dependencies are installed\n- Ensure sufficient system permissions\n\n2. **Media Processing Errors**\n\n```bash\nError: Failed to process media file\n```\n\n- Verify file format is supported\n- Check available system memory\n- Ensure ffmpeg is properly installed\n\n3. **AWS S3 Connection Issues**\n\n```bash\nError: AWS credentials not configured\n```\n\n- Verify AWS credentials are set\n- Check S3 bucket permissions\n- Ensure correct region configuration\n\n### Debug Mode\n\nEnable debug logging for detailed troubleshooting:\n\n```typescript\nprocess.env.DEBUG = \"eliza:plugin-node:*\";\n```\n\n### System Requirements\n\n- Node.js 16.x or higher\n- FFmpeg for media processing\n- Minimum 4GB RAM recommended\n- CUDA-compatible GPU (optional, for ML features)\n\n### Performance Optimization\n\n1. **Cache Management**\n   - Regular cleanup of `content_cache` directory\n   - Implement cache size limits\n   - Monitor disk usage\n\n2. **Memory Usage**\n   - Configure max buffer sizes\n   - Implement streaming for large files\n   - Monitor memory consumption\n\n3. **Concurrent Operations**\n   - Adjust queue size limits\n   - Configure worker threads\n   - Monitor process pool\n\n## Support\n\nFor issues and feature requests, please:\n\n1. Check the troubleshooting guide above\n2. Review existing GitHub issues\n3. Submit a new issue with:\n   - System information\n   - Error logs\n   - Steps to reproduce\n\n## Future Enhancements\n\n1. **File Operations**\n   - Enhanced streaming capabilities\n   - Advanced compression options\n   - Batch file processing\n   - File type detection\n   - Metadata management\n   - Version control integration\n\n2. **Media Processing**\n   - Additional video formats\n   - Advanced image processing\n   - Audio enhancement tools\n   - Real-time processing\n   - Quality optimization\n   - Format conversion\n\n3. **Cloud Integration**\n   - Multi-cloud support\n   - Advanced caching\n   - CDN optimization\n   - Auto-scaling features\n   - Cost optimization\n   - Backup automation\n\n4. **Speech Services**\n   - Additional voice models\n   - Language expansion\n   - Emotion detection\n   - Voice cloning\n   - Real-time synthesis\n   - Custom voice training\n\n5. **Browser Automation**\n   - Headless optimization\n   - Parallel processing\n   - Session management\n   - Cookie handling\n   - Proxy support\n   - Resource optimization\n\n6. **Security Features**\n   - Enhanced encryption\n   - Access control\n   - Audit logging\n   - Threat detection\n   - Rate limiting\n   - Compliance tools\n\n7. **Performance Optimization**\n   - Memory management\n   - CPU utilization\n   - Concurrent operations\n   - Resource pooling\n   - Cache strategies\n   - Load balancing\n\n8. **Developer Tools**\n   - Enhanced debugging\n   - Testing framework\n   - Documentation generator\n   - CLI improvements\n   - Monitoring tools\n   - Integration templates\n\nWe welcome community feedback and contributions to help prioritize these enhancements.\n\n## Contributing\n\nContributions are welcome! Please see the [CONTRIBUTING.md](CONTRIBUTING.md) file for more information.\n\n## Credits\n\nThis plugin integrates with and builds upon several key technologies:\n\n- [Node.js](https://nodejs.org/) - The core runtime environment\n- [FFmpeg](https://ffmpeg.org/) - Media processing capabilities\n- [ElevenLabs](https://elevenlabs.io/) - Voice synthesis\n- [OpenAI](https://openai.com/) - Transcription and AI services\n- [AWS S3](https://aws.amazon.com/s3/) - Cloud storage\n- [Playwright](https://playwright.dev/) - Browser automation\n- [LLaMA](https://github.com/facebookresearch/llama) - Local language models\n- [VITS](https://github.com/jaywalnut310/vits) - Voice synthesis\n- [Deepgram](https://deepgram.com/) - Speech recognition\n- [Sharp](https://sharp.pixelplumbing.com/) - Image processing\n\nSpecial thanks to:\n\n- The Node.js community and all the open-source contributors who make these integrations possible.\n- The Eliza community for their contributions and feedback.\n\nFor more information about Node.js capabilities:\n\n- [Node.js Documentation](https://nodejs.org/en/docs/)\n- [Node.js Developer Portal](https://nodejs.org/en/about/)\n- [Node.js GitHub Repository](https://github.com/nodejs/node)\n\n## License\n\nThis plugin is part of the Eliza project. See the main project repository for license information.\n","readmeFilename":"README.md"}