{"id":31287950,"url":"https://github.com/mxrqz/snap","last_synced_at":"2026-04-02T03:10:41.747Z","repository":{"id":313679071,"uuid":"1051374629","full_name":"mxrqz/Snap","owner":"mxrqz","description":"Snap. Style. Share. Crie capturas de tela elegantes, prontas para portfolios, redes sociais e apresentações.","archived":false,"fork":false,"pushed_at":"2025-09-14T20:36:28.000Z","size":41892,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-14T21:36:23.420Z","etag":null,"topics":["bun","nextjs","reactjs","tailwindcss","typescript","vercel"],"latest_commit_sha":null,"homepage":"https://snap.mxrqz.com","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mxrqz.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-05T22:00:47.000Z","updated_at":"2025-09-14T20:36:32.000Z","dependencies_parsed_at":"2025-09-07T20:29:32.120Z","dependency_job_id":"f925024d-c28b-4ad5-b162-2a6317c98928","html_url":"https://github.com/mxrqz/Snap","commit_stats":null,"previous_names":["mxrqz/snap"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/mxrqz/Snap","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mxrqz%2FSnap","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mxrqz%2FSnap/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mxrqz%2FSnap/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mxrqz%2FSnap/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mxrqz","download_url":"https://codeload.github.com/mxrqz/Snap/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mxrqz%2FSnap/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":276740994,"owners_count":25696501,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-24T02:00:09.776Z","response_time":97,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bun","nextjs","reactjs","tailwindcss","typescript","vercel"],"created_at":"2025-09-24T11:37:46.477Z","updated_at":"2025-09-24T11:37:51.037Z","avatar_url":"https://github.com/mxrqz.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 📸 Snap API\n\n\u003e Beautiful styled screenshots API powered by Microlink - Create ray.so-style images for websites\n\n[![API Status](https://img.shields.io/badge/status-active-brightgreen)](http://localhost:3000/api/health)\n[![TypeScript](https://img.shields.io/badge/TypeScript-007ACC?logo=typescript\u0026logoColor=white)](https://www.typescriptlang.org/)\n[![Next.js](https://img.shields.io/badge/Next.js-black?logo=next.js\u0026logoColor=white)](https://nextjs.org/)\n[![OpenAPI](https://img.shields.io/badge/OpenAPI-3.0-brightgreen)](http://localhost:3000/api/docs)\n\nTransform any website into a beautiful, styled screenshot with custom gradients, shadows, browser mockups, and more. Perfect for social media, presentations, and portfolios.\n\n## ✨ Features\n\n- 🎨 **Custom Styling**: Gradients, solid colors, borders, shadows\n- 🌐 **Browser Mockups**: Safari, Chrome, Firefox, Edge frames\n- 📱 **Responsive**: Custom viewport sizes and mobile simulation\n- ⚡ **Fast**: Built with Bun for maximum performance\n- 🔒 **Type Safe**: Full TypeScript implementation with Zod validation\n- 📚 **Well Documented**: Complete OpenAPI/Swagger documentation\n- 🖼️ **Multiple Outputs**: JSON API, HTML preview, CLI tools\n\n## 🚀 Quick Start\n\n### Prerequisites\n\n- [Bun](https://bun.sh/) installed on your system\n- Node.js 18+ (for compatibility)\n\n### Installation\n\n```bash\n# Clone the repository\ngit clone \u003cyour-repo-url\u003e\ncd snap\n\n# Install dependencies\nbun install\n\n# Start the development server\nbun run dev\n```\n\nThe API will be available at `http://localhost:3000`\n\n## 📖 Documentation\n\n### Interactive API Documentation\n\nVisit `http://localhost:3000/api/docs` for complete interactive Swagger UI documentation with:\n\n- 📝 Detailed endpoint descriptions\n- 🧪 Try-it-out functionality\n- 📋 Request/response examples\n- 🔧 Parameter validation\n\n### Quick Reference\n\n| Endpoint | Method | Description |\n|----------|---------|-------------|\n| `/` | GET | Next.js home page |\n| `/api` | GET | API information and endpoints |\n| `/api/health` | GET | Health check |\n| `/api/snap` | GET/POST | Generate styled screenshot |\n| `/api/preview` | GET | Browser preview with download |\n| `/api/docs` | GET | Swagger UI documentation |\n| `/openapi.json` | GET | OpenAPI specification |\n\n## 🎯 Usage Examples\n\n### 1. Simple Screenshot (GET)\n\n```bash\ncurl \"http://localhost:3000/api/snap?url=https://example.com\"\n```\n\n### 2. Styled Screenshot (GET)\n\n```bash\ncurl \"http://localhost:3000/api/snap?url=https://github.com\u0026borderRadius=15\u0026margin=40\u0026browserMockup=safari\"\n```\n\n### 3. Advanced Configuration (POST)\n\n```bash\ncurl -X POST \"http://localhost:3000/api/snap\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"url\": \"https://tailwindcss.com\",\n    \"screenshot\": {\n      \"viewport\": {\n        \"width\": 1280,\n        \"height\": 720\n      },\n      \"colorScheme\": \"dark\",\n      \"delay\": 3000\n    },\n    \"style\": {\n      \"borderRadius\": 12,\n      \"margin\": 60,\n      \"background\": {\n        \"type\": \"gradient\",\n        \"direction\": \"to-r\",\n        \"colors\": [\n          {\"color\": \"#FF6B6B\", \"position\": 0},\n          {\"color\": \"#4ECDC4\", \"position\": 50},\n          {\"color\": \"#45B7D1\", \"position\": 100}\n        ]\n      },\n      \"browserMockup\": \"chrome\",\n      \"shadow\": {\n        \"enabled\": true,\n        \"blur\": 25,\n        \"offsetY\": 15,\n        \"opacity\": 0.2\n      }\n    }\n  }'\n```\n\n### 4. Browser Preview\n\n```bash\n# Open in browser\nopen \"http://localhost:3000/api/preview?url=https://example.com\u0026borderRadius=15\u0026margin=40\"\n```\n\n### 5. Save to File (CLI)\n\n```bash\n# Simple save\nbun save-image.ts https://example.com\n\n# With styling options\nbun save-image.ts https://github.com \\\n  --border-radius 15 \\\n  --margin 40 \\\n  --background \"#ffffff\" \\\n  --browser safari \\\n  --output my-screenshot.png\n```\n\n## 🎨 Styling Options\n\n### Background Types\n\n#### Solid Color\n```json\n{\n  \"background\": {\n    \"type\": \"solid\",\n    \"color\": \"#ffffff\"\n  }\n}\n```\n\n#### Gradient\n```json\n{\n  \"background\": {\n    \"type\": \"gradient\",\n    \"direction\": \"to-br\",\n    \"colors\": [\n      {\"color\": \"#667eea\", \"position\": 0},\n      {\"color\": \"#764ba2\", \"position\": 100}\n    ]\n  }\n}\n```\n\n**Gradient Directions**: `to-r`, `to-l`, `to-t`, `to-b`, `to-br`, `to-bl`, `to-tr`, `to-tl`\n\n### Browser Mockups\n\n- `safari` - Safari browser with macOS styling\n- `chrome` - Chrome browser with clean design\n- `firefox` - Firefox browser styling\n- `edge` - Microsoft Edge styling\n- `none` - No browser frame (default)\n\n### Shadow Configuration\n\n```json\n{\n  \"shadow\": {\n    \"enabled\": true,\n    \"blur\": 20,\n    \"offsetX\": 0,\n    \"offsetY\": 10,\n    \"color\": \"#000000\",\n    \"opacity\": 0.15\n  }\n}\n```\n\n### Viewport Options\n\n```json\n{\n  \"viewport\": {\n    \"width\": 1920,\n    \"height\": 1080,\n    \"isMobile\": false,\n    \"deviceScaleFactor\": 1\n  }\n}\n```\n\n## 📊 API Response Format\n\n### Success Response\n\n```json\n{\n  \"success\": true,\n  \"imageUrl\": \"data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAA...\",\n  \"metadata\": {\n    \"originalUrl\": \"https://example.com\",\n    \"processedAt\": \"2023-12-07T10:30:00.000Z\",\n    \"dimensions\": {\n      \"width\": 1984,\n      \"height\": 1144\n    }\n  }\n}\n```\n\n### Error Response\n\n```json\n{\n  \"success\": false,\n  \"error\": \"Validation error: Invalid URL format\"\n}\n```\n\n## 🔧 Configuration Parameters\n\n### Screenshot Parameters\n\n| Parameter | Type | Range | Default | Description |\n|-----------|------|-------|---------|-------------|\n| `url` | string | URI | required | Website URL to screenshot |\n| `waitUntil` | string | enum | `networkidle0` | When to consider loading complete |\n| `delay` | integer | 0-10000 | 2000 | Additional delay in milliseconds |\n| `colorScheme` | string | light/dark | `dark` | Page color scheme preference |\n\n### Style Parameters\n\n| Parameter | Type | Range | Default | Description |\n|-----------|------|-------|---------|-------------|\n| `borderRadius` | integer | 0-50 | 8 | Border radius in pixels |\n| `margin` | integer | 0-200 | 32 | Margin around image |\n| `browserMockup` | string | enum | `none` | Browser frame style |\n\n### Viewport Parameters\n\n| Parameter | Type | Range | Default | Description |\n|-----------|------|-------|---------|-------------|\n| `viewport.width` | integer | 320-4096 | 1920 | Viewport width |\n| `viewport.height` | integer | 240-4096 | 1080 | Viewport height |\n| `viewport.isMobile` | boolean | - | false | Mobile simulation |\n| `viewport.deviceScaleFactor` | number | 0.5-3 | 1 | Device pixel ratio |\n\n## 🧪 Testing\n\nRun the test suite:\n\n```bash\n# Run all tests\nbun test\n\n# Run specific test file\nbun test test/validation.test.ts\n\n# Run integration tests (requires server running)\nbun run dev  # In another terminal\nbun test test/integration.test.ts\n```\n\n## 📁 Project Structure\n\n```\nsnap/\n├── index.ts              # Main server and API endpoints\n├── types.ts              # TypeScript type definitions\n├── validation.ts         # Zod validation schemas\n├── openapi.json          # OpenAPI/Swagger specification\n├── save-image.ts         # CLI tool for saving images\n├── demo.ts              # Usage examples and demos\n├── services/\n│   ├── microlink.ts     # Microlink API integration\n│   ├── image-processor.ts # Image styling with Sharp\n│   └── browser-mockup.ts # Browser frame generation\n├── test/\n│   ├── validation.test.ts\n│   ├── microlink-service.test.ts\n│   └── integration.test.ts\n└── screenshots/         # Output directory for saved images\n```\n\n## 🚨 Error Handling\n\nThe API provides detailed error messages for different failure scenarios:\n\n- **400 Bad Request**: Invalid parameters or malformed requests\n- **503 Service Unavailable**: Microlink API unavailable or rate limited\n- **500 Internal Server Error**: Image processing or server errors\n\nAll errors follow the consistent format:\n\n```json\n{\n  \"success\": false,\n  \"error\": \"Descriptive error message\"\n}\n```\n\n## 🔄 Rate Limiting\n\nThis API uses the Microlink service for screenshots. Be mindful of:\n\n- Microlink's rate limits and pricing\n- Large images may take longer to process\n- Complex styling operations increase processing time\n\n## 🤝 Contributing\n\n1. Fork the repository\n2. Create a feature branch: `git checkout -b feature-name`\n3. Make your changes and add tests\n4. Ensure all tests pass: `bun test`\n5. Submit a pull request\n\n## 📄 License\n\nMIT License - see LICENSE file for details.\n\n## 🙏 Acknowledgments\n\n- [Microlink](https://microlink.io/) for the screenshot API\n- [Sharp](https://sharp.pixelplumbing.com/) for image processing\n- [Bun](https://bun.sh/) for the runtime\n- [Zod](https://zod.dev/) for validation\n\n---\n\n**Ready to create beautiful screenshots?** 🚀\n\nStart the server with `bun run dev` and visit `http://localhost:3000/api/docs` for interactive documentation!","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmxrqz%2Fsnap","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmxrqz%2Fsnap","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmxrqz%2Fsnap/lists"}