{"_id":"@agb-npm/firestore-backup-restore-gui","_rev":"2-1380a7713da30ab270810574bab9c197","name":"@agb-npm/firestore-backup-restore-gui","dist-tags":{"latest":"1.0.1"},"versions":{"1.0.0":{"name":"@agb-npm/firestore-backup-restore-gui","version":"1.0.0","keywords":["firestore","firebase","backup","restore","gui","nextjs","typescript","web-interface"],"author":"","license":"MIT","_id":"@agb-npm/firestore-backup-restore-gui@1.0.0","maintainers":[{"name":"bekitashi","email":"agokselb@gmail.com"}],"homepage":"https://github.com/yourusername/firestore-restore-gui#readme","bugs":{"url":"https://github.com/yourusername/firestore-restore-gui/issues"},"dist":{"shasum":"c9744ba6c5402f2a5a144ea79941e23649b8dac3","tarball":"https://registry.npmjs.org/@agb-npm/firestore-backup-restore-gui/-/firestore-backup-restore-gui-1.0.0.tgz","fileCount":20,"integrity":"sha512-a7XCjZqu5t1iXt9nqRBU/OBCRl1V8BaJjAsoIbMzCofMRj3X2/NGrWPQ74CvOUE7Kh6X6n77DoFlLbKg/uqpJA==","signatures":[{"sig":"MEQCIC5YaFhwe1CQuBeHT6V3Q39MYZfXZkwmzV6eIOtcOX39AiBdgZHJUeAoJwmfGeR7f7xi8w5OQWrZk9kCqXGgSk1C8w==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":49630},"main":"index.js","gitHead":"7061f1958ecd301082cb37b11e4375c9beea153f","scripts":{"dev":"next dev","lint":"next lint","build":"next build","start":"next start"},"_npmUser":{"name":"bekitashi","email":"agokselb@gmail.com"},"repository":{"url":"git+https://github.com/yourusername/firestore-restore-gui.git","type":"git"},"_npmVersion":"10.9.4","description":"Beautiful GUI for Firestore backup restore operations","directories":{},"_nodeVersion":"22.21.1","dependencies":{"clsx":"^2.1.1","next":"14.2.5","react":"18.3.1","react-dom":"18.3.1","lucide-react":"^0.460.0"},"_hasShrinkwrap":false,"devDependencies":{"eslint":"^8.57.1","postcss":"^8.4.45","typescript":"^5.6.3","@types/node":"^20.16.4","tailwindcss":"^3.4.13","@types/react":"^18.3.5","autoprefixer":"^10.4.20","@types/react-dom":"^18.3.0","eslint-config-next":"14.2.5"},"_npmOperationalInternal":{"tmp":"tmp/firestore-backup-restore-gui_1.0.0_1764442727953_0.6416042537331204","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@agb-npm/firestore-backup-restore-gui","version":"1.0.1","description":"Beautiful GUI for Firestore backup restore operations","main":"index.js","scripts":{"dev":"next dev","build":"next build","start":"next start","lint":"next lint"},"keywords":["firestore","firebase","backup","restore","gui","nextjs","typescript","web-interface"],"author":"","license":"MIT","repository":{"type":"git","url":"git+https://github.com/agb/firestore-restore-gui.git"},"dependencies":{"next":"14.2.5","react":"18.3.1","react-dom":"18.3.1","lucide-react":"^0.460.0","clsx":"^2.1.1"},"devDependencies":{"@types/node":"^20.16.4","@types/react":"^18.3.5","@types/react-dom":"^18.3.0","autoprefixer":"^10.4.20","eslint":"^8.57.1","eslint-config-next":"14.2.5","postcss":"^8.4.45","tailwindcss":"^3.4.13","typescript":"^5.6.3"},"_id":"@agb-npm/firestore-backup-restore-gui@1.0.1","gitHead":"7061f1958ecd301082cb37b11e4375c9beea153f","bugs":{"url":"https://github.com/agb/firestore-restore-gui/issues"},"homepage":"https://github.com/agb/firestore-restore-gui#readme","_nodeVersion":"22.21.1","_npmVersion":"10.9.4","dist":{"integrity":"sha512-5eWMjc1VNVhvOjzORwtqMqPEx1bFEmBtPt9I/O++2mU8QaLk1NzPRbRP1cHZy8NtWc5mFfA6pBo3e9tsZa/HGA==","shasum":"663d108113b54ec1663c98ac3465f0f0324a2d2b","tarball":"https://registry.npmjs.org/@agb-npm/firestore-backup-restore-gui/-/firestore-backup-restore-gui-1.0.1.tgz","fileCount":20,"unpackedSize":49621,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIG9QLtEDlqcUHtZLJtBMV4faiGeVl50f+lOJ0Ox4dG87AiEAyLlZ2780QQCfyZ6bxP6O4wOQayLj+Xyu7yHEOc6L7dU="}]},"_npmUser":{"name":"bekitashi","email":"agokselb@gmail.com"},"directories":{},"maintainers":[{"name":"bekitashi","email":"agokselb@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/firestore-backup-restore-gui_1.0.1_1764442794759_0.9719255276056218"},"_hasShrinkwrap":false}},"time":{"created":"2025-11-29T18:58:47.894Z","modified":"2025-11-29T18:59:55.188Z","1.0.0":"2025-11-29T18:58:48.160Z","1.0.1":"2025-11-29T18:59:54.963Z"},"bugs":{"url":"https://github.com/agb/firestore-restore-gui/issues"},"license":"MIT","homepage":"https://github.com/agb/firestore-restore-gui#readme","keywords":["firestore","firebase","backup","restore","gui","nextjs","typescript","web-interface"],"repository":{"type":"git","url":"git+https://github.com/agb/firestore-restore-gui.git"},"description":"Beautiful GUI for Firestore backup restore operations","maintainers":[{"name":"bekitashi","email":"agokselb@gmail.com"}],"readme":"# Firestore Backup Restore GUI\n\nBeautiful, user-friendly web interface for restoring Firestore database backups. This tool simplifies the process of restoring Firebase Firestore backups with an intuitive step-by-step wizard.\n\n![Firestore Restore GUI](https://img.shields.io/badge/Firestore-Restore-pink?style=for-the-badge)\n![Next.js](https://img.shields.io/badge/Next.js-14-black?style=for-the-badge&logo=next.js)\n![TypeScript](https://img.shields.io/badge/TypeScript-5-blue?style=for-the-badge&logo=typescript)\n![License](https://img.shields.io/badge/License-MIT-pink?style=for-the-badge)\n\n## Why This Tool?\n\n### The Location Mismatch Problem\n\nWhen trying to restore Firestore backups, you might encounter this frustrating error:\n\n```\nINVALID_ARGUMENT: Bucket your-project.firebasestorage.app is in location us-central1. \nThis database can only operate on buckets spanning location asia or asia-northeast1.\n```\n\n**The Problem:**\n- Firestore databases are region-specific (e.g., `asia-northeast1`)\n- Backup files stored in Firebase Storage may be in a different region (e.g., `us-central1`)\n- Firestore import operations require the backup bucket to be in a compatible region\n- The `gcloud firestore import` command fails if there's a location mismatch\n\n**Why This Tool Was Created:**\nThis tool was specifically developed to solve the location mismatch issue. It provides:\n- Clear visibility of the problem with error messages\n- Step-by-step wizard to guide you through the restore process\n- Automatic handling of location compatibility\n- Real-time monitoring of restore operations\n- User-friendly interface instead of complex command-line operations\n\nInstead of manually copying buckets, dealing with gcloud CLI commands, and troubleshooting location errors, this GUI simplifies the entire process into an intuitive, step-by-step workflow.\n\n## Features\n\n- **Beautiful Sakura-themed UI** - Clean, modern interface inspired by cherry blossoms\n- **gcloud Authentication** - Easy Google Cloud authentication\n- **Backup Selection** - Browse and select backups from Firebase Storage\n- **Restore Wizard** - Step-by-step restore process with progress tracking\n- **Real-time Status** - Monitor restore operations in real-time\n- **Detailed Logs** - See exactly what's happening during restore\n- **Fast & Efficient** - Optimized for quick restore operations\n\n## Quick Start\n\n### Prerequisites\n\n- Node.js 18+ installed\n- gcloud CLI installed (or will be installed automatically)\n- Google Cloud account with Firestore access\n\n### Installation\n\n```bash\n# Clone or download this repository\ncd firestore-restore-gui\n\n# Install dependencies\nnpm install\n# or\npnpm install\n# or\nyarn install\n\n# Start development server\nnpm run dev\n# or\npnpm dev\n```\n\nOpen [http://localhost:3000](http://localhost:3000) in your browser.\n\n## Usage Guide\n\n### Step 1: Authentication\n\nThe GUI automatically checks if gcloud CLI is installed and if you're authenticated.\n\n1. If gcloud CLI is not installed, follow the installation instructions shown\n2. Run `gcloud auth login` in your terminal\n3. Refresh the GUI page\n4. You should see \"Authenticated!\" with your account info\n\n### Step 2: Select Database\n\nChoose the target Firestore database:\n- **Select Project**: Choose from dropdown or use current project\n- **Select Database**: Choose database ID (default: `(default)` or custom like `miraku-jp`)\n\n### Step 3: Choose Backup Source\n\n**Option A: Browse Backups**\n- Click \"Browse Backups\" tab\n- Available backups from Firebase Storage are listed\n- Click on a backup to select it\n\n**Option B: Manual Path**\n- Click \"Manual Path\" tab\n- Enter Google Cloud Storage path manually\n- Format: `gs://bucket-name/folder-name`\n- Example: `gs://my-project.firebasestorage.app/2025-11-29T17:04:03_93838`\n\n### Step 4: Review & Confirm\n\nReview your restore configuration:\n- Project ID\n- Database ID\n- Backup path\n- Warning about data overwriting\n\n### Step 5: Start Restore\n\n- Click \"Start Restore\" button\n- Operation starts in background\n- Automatically moves to progress monitoring\n\n### Step 6: Monitor Progress\n\n- Real-time status updates (checks every 3 seconds)\n- Operation ID displayed\n- Start/completion timestamps\n- Success/error notifications\n\n## Features in Detail\n\n### Backup Browser\n\n- List all backups in Firebase Storage\n- Quick selection with visual feedback\n- Backup path display\n\n### Restore Wizard\n\nStep-by-step process:\n1. Authentication\n2. Database Selection\n3. Backup Selection\n4. Review Configuration\n5. Restore Execution\n6. Completion\n\n### Status Monitoring\n\n- Operation status tracking\n- Real-time updates (polling every 3 seconds)\n- Error handling\n- Success notifications\n\n## Configuration\n\n### Environment Variables\n\nCreate a `.env.local` file (optional):\n\n```env\n# Optional: Default project ID\nNEXT_PUBLIC_DEFAULT_PROJECT_ID=your-project-id\n\n# Optional: Default database ID\nNEXT_PUBLIC_DEFAULT_DATABASE_ID=(default)\n```\n\n### gcloud CLI\n\nThe GUI uses gcloud CLI for operations. If not installed:\n\n- The GUI will show installation instructions\n- Or install manually: https://cloud.google.com/sdk/docs/install\n\n## Project Structure\n\n```\nfirestore-restore-gui/\n├── app/                 # Next.js app directory\n│   ├── api/            # API routes\n│   │   ├── auth/       # Authentication endpoints\n│   │   ├── backups/    # Backup listing endpoints\n│   │   ├── databases/  # Database listing endpoints\n│   │   ├── projects/   # Project listing endpoints\n│   │   └── restore/    # Restore operation endpoints\n│   ├── globals.css     # Global styles\n│   ├── layout.tsx      # Root layout\n│   └── page.tsx        # Main page\n├── components/         # React components\n│   └── RestoreWizard.tsx  # Main wizard component\n├── lib/               # Utility functions\n│   └── gcloud.ts      # gcloud CLI wrapper\n└── public/            # Static assets\n```\n\n## API Endpoints\n\n### `/api/auth/status`\nCheck authentication status\n\n### `/api/projects`\nList all available Google Cloud projects\n\n### `/api/databases?projectId=PROJECT_ID`\nList all databases in a project\n\n### `/api/backups?projectId=PROJECT_ID`\nList available backups in Firebase Storage for a project\n\n### `/api/restore/start`\nStart restore operation (POST with body: `{backupPath, projectId, databaseId}`)\n\n### `/api/restore/status?operationName=OP_NAME&projectId=PROJECT_ID&databaseId=DB_ID`\nGet restore operation status\n\n## UI Design\n\nThe GUI follows the Sakura theme:\n- **Colors**: Pink and light pink tones (`pink-50`, `pink-100`, `pink-300`, `pink-400`, `pink-500`)\n- **Style**: Clean, minimalist design\n- **UX**: Intuitive step-by-step wizard\n- **Responsive**: Works on all screen sizes\n\n## Troubleshooting\n\n### gcloud CLI Not Found\n\n```bash\n# Install via snap (Linux)\nsudo snap install google-cloud-cli\n\n# Or install manually\ncurl https://sdk.cloud.google.com | bash\n```\n\n### Authentication Issues\n\n```bash\ngcloud auth login\ngcloud config set project YOUR_PROJECT_ID\n```\n\n### Permission Errors\n\nEnsure your Google Cloud account has:\n- Firestore Admin permissions\n- Storage Admin permissions\n\n### Location Mismatch Error\n\n**Common Error:**\n```\nINVALID_ARGUMENT: Bucket PROJECT_ID.firebasestorage.app is in location us-central1. \nThis database can only operate on buckets spanning location asia or asia-northeast1.\n```\n\n**What This Means:**\nYour Firestore database is in one region (e.g., `asia-northeast1`), but your backup is stored in a different region (e.g., `us-central1`). Firestore import operations require the backup bucket to be in a compatible location.\n\n**Solution:**\n1. **Check your database location:**\n   - Go to Firebase Console → Firestore Database\n   - Check the region shown (e.g., `asia-northeast1`)\n\n2. **Check your backup bucket location:**\n   - Go to Firebase Console → Storage\n   - Check the bucket region\n\n3. **If locations don't match:**\n   - Create a new Storage bucket in the same region as your Firestore database\n   - Copy the backup files to the new bucket\n   - Use the new bucket path for restore\n\n4. **Alternative:** Use this GUI tool, which guides you through the process and helps identify location mismatches early.\n\n### Database Not Found\n\n- Verify database ID is correct (not always `(default)`)\n- Check database exists in Firebase Console\n- Ensure you have proper permissions\n\n## Contributing\n\nContributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for details.\n\n## License\n\nMIT License - See [LICENSE](LICENSE) for details.\n\n## Acknowledgments\n\n- Built with Next.js 14\n- UI inspired by Sakura theme\n- Powered by Google Cloud Platform\n- Icons from Lucide React\n\n## Support\n\nFor issues or questions:\n1. Check the Troubleshooting section\n2. Open an issue on GitHub\n3. Review the detailed logs in the GUI\n\n---\n\nMade for the Firebase community\n","readmeFilename":"README.md"}