chore: import upstream snapshot with attribution
This commit is contained in:
wehub-resource-sync
+187
@@ -0,0 +1,187 @@
|
||||
# API - Vercel Serverless Functions
|
||||
|
||||
Critical infrastructure for claude-code-templates component ecosystem.
|
||||
|
||||
## ⚠️ CRITICAL ENDPOINTS
|
||||
|
||||
These endpoints are essential for component download metrics. **DO NOT BREAK THEM.**
|
||||
|
||||
### `/api/track-download-supabase` 🔴
|
||||
|
||||
Tracks every component installation from the CLI tool.
|
||||
|
||||
**Used by**: `cli-tool/bin/create-claude-config.js`
|
||||
|
||||
**Called on**: Every `--agent`, `--command`, `--mcp`, `--hook`, `--setting`, `--skill` installation
|
||||
|
||||
**Database**: Supabase (component_downloads, download_stats)
|
||||
|
||||
### `/api/discord/interactions` 🟡
|
||||
|
||||
Discord bot for component discovery and search.
|
||||
|
||||
**Features**: `/search`, `/info`, `/install`, `/popular`, `/random`
|
||||
|
||||
### `/api/claude-code-check` 🟢
|
||||
|
||||
Monitors Claude Code releases and sends Discord notifications.
|
||||
|
||||
**Frequency**: Every 4 hours (Vercel Cron)
|
||||
|
||||
**Database**: Neon (claude_code_versions, claude_code_changes)
|
||||
|
||||
## 🧪 Testing
|
||||
|
||||
**ALWAYS run tests before deploying:**
|
||||
|
||||
```bash
|
||||
# Run all tests
|
||||
npm test
|
||||
|
||||
# Run only critical endpoint tests
|
||||
npm run test:api
|
||||
|
||||
# Watch mode
|
||||
npm run test:watch
|
||||
|
||||
# With coverage
|
||||
npm run test:coverage
|
||||
```
|
||||
|
||||
## 🚀 Deployment
|
||||
|
||||
### Pre-Deployment Checklist
|
||||
|
||||
```bash
|
||||
# 1. Run validation script (from project root)
|
||||
./scripts/predeploy-check.sh
|
||||
|
||||
# 2. If checks pass, deploy
|
||||
vercel --prod
|
||||
```
|
||||
|
||||
### Manual Deploy Steps
|
||||
|
||||
```bash
|
||||
# 1. Install dependencies
|
||||
npm install
|
||||
|
||||
# 2. Run tests
|
||||
npm run test:api
|
||||
|
||||
# 3. Deploy
|
||||
cd ..
|
||||
vercel --prod
|
||||
```
|
||||
|
||||
## 📁 File Structure
|
||||
|
||||
```
|
||||
api/
|
||||
├── track-download-supabase.js # Component download tracking (CRITICAL)
|
||||
├── claude-code-check.js # Claude Code changelog monitor
|
||||
├── _parser-claude.js # Changelog parser utility
|
||||
├── discord/
|
||||
│ └── interactions.js # Discord bot handler
|
||||
├── claude-code-monitor/
|
||||
│ ├── README.md # Detailed docs
|
||||
│ ├── check-version.js # Version checker
|
||||
│ ├── discord-notifier.js # Discord notifications
|
||||
│ ├── parser.js # Changelog parser
|
||||
│ └── webhook.js # NPM webhook handler
|
||||
├── __tests__/
|
||||
│ └── endpoints.test.js # Critical endpoint tests
|
||||
├── jest.config.cjs # Jest configuration
|
||||
├── package.json # Dependencies & scripts
|
||||
└── README.md # This file
|
||||
```
|
||||
|
||||
## 🔧 Environment Variables
|
||||
|
||||
Required in Vercel Dashboard:
|
||||
|
||||
```bash
|
||||
# Supabase
|
||||
SUPABASE_URL=xxx
|
||||
SUPABASE_SERVICE_ROLE_KEY=xxx
|
||||
|
||||
# Neon Database
|
||||
NEON_DATABASE_URL=xxx
|
||||
|
||||
# Discord
|
||||
DISCORD_APP_ID=xxx
|
||||
DISCORD_BOT_TOKEN=xxx
|
||||
DISCORD_PUBLIC_KEY=xxx
|
||||
DISCORD_WEBHOOK_URL_CHANGELOG=xxx
|
||||
```
|
||||
|
||||
## 🐛 Troubleshooting
|
||||
|
||||
### Tests Failing?
|
||||
|
||||
```bash
|
||||
# Test against production
|
||||
API_BASE_URL=https://aitmpl.com npm run test:api
|
||||
|
||||
# Check specific endpoint
|
||||
curl -X POST https://aitmpl.com/api/track-download-supabase \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"type":"agent","name":"test","path":"test/path"}'
|
||||
```
|
||||
|
||||
### Endpoint Not Found After Deploy?
|
||||
|
||||
1. Check Vercel function logs: `vercel logs aitmpl.com --follow`
|
||||
2. Verify file is in `/api` root (not nested)
|
||||
3. Ensure proper export: `export default async function handler(req, res) {}`
|
||||
|
||||
### No Download Tracking Data?
|
||||
|
||||
1. Check Vercel logs
|
||||
2. Verify environment variables are set
|
||||
3. Test endpoint manually (see above)
|
||||
4. Check Supabase table: `select * from component_downloads order by created_at desc limit 10;`
|
||||
|
||||
## 📊 Monitoring
|
||||
|
||||
### Vercel Dashboard
|
||||
|
||||
https://vercel.com/dashboard → aitmpl → Functions
|
||||
|
||||
### Real-time Logs
|
||||
|
||||
```bash
|
||||
vercel logs aitmpl.com --follow
|
||||
```
|
||||
|
||||
### Database Queries
|
||||
|
||||
**Supabase**:
|
||||
```sql
|
||||
SELECT type, name, COUNT(*) as downloads
|
||||
FROM component_downloads
|
||||
WHERE download_timestamp > NOW() - INTERVAL '7 days'
|
||||
GROUP BY type, name
|
||||
ORDER BY downloads DESC;
|
||||
```
|
||||
|
||||
**Neon**:
|
||||
```sql
|
||||
SELECT version, published_at, discord_notified
|
||||
FROM claude_code_versions
|
||||
ORDER BY published_at DESC;
|
||||
```
|
||||
|
||||
## 🆘 Emergency Rollback
|
||||
|
||||
```bash
|
||||
# 1. List recent deployments
|
||||
vercel ls
|
||||
|
||||
# 2. Promote previous working deployment
|
||||
vercel promote <previous-deployment-url>
|
||||
```
|
||||
|
||||
## 📖 More Info
|
||||
|
||||
See `../CLAUDE.md` section "API Architecture & Deployment" for detailed documentation.
|
||||
Reference in New Issue
Block a user