davila7__claude-code-templates/docs/api

API Directory - Documentation

This directory contains both static files and serverless functions for the Claude Code Templates project deployed on Vercel.

📁 Structure Overview

docs/api/
├── README.md                      # This file
├── agents.json                    # Static JSON file for agent queries
├── package.json                   # Dependencies for serverless functions
└── track-download-supabase.js     # Serverless function for download tracking

🔍 Why This Structure?

The project is configured with "outputDirectory": "docs" in vercel.json, which means:

• Vercel serves all content from the /docs/ directory
• Serverless functions must be located at /docs/api/ to be recognized
• Static files are also served from this same directory

Original Structure (Before Fix)

Previously, there were two separate API directories:

/api/                              # ❌ Not detected by Vercel
├── track-download-supabase.js     # Serverless function (404 error)
└── package.json

/docs/api/                         # ✅ Served correctly
└── agents.json                    # Static file

Problem: The serverless function in /api/ was not being detected by Vercel because the outputDirectory was set to docs, causing 404 errors when trying to track downloads.

Current Structure (After Fix)

/docs/api/                         # ✅ Everything in one place
├── agents.json                    # Static file for queries
├── track-download-supabase.js     # Serverless function for tracking
└── package.json                   # Dependencies

Solution: All API-related files (both static and serverless) are now in /docs/api/, ensuring Vercel can find and execute them correctly.

---

📄 File Descriptions

1. agents.json (Static File)

• Type: Static JSON data
• Purpose: Contains the list of available agents for the frontend
• Accessed by: Frontend application via fetch/axios
• URL: https://www.aitmpl.com/api/agents.json
• Size: ~25KB
• Updates: Generated by generate_components_json.py script

Usage:

fetch('https://www.aitmpl.com/api/agents.json')
  .then(res => res.json())
  .then(data => console.log(data));

---

2. track-download-supabase.js (Serverless Function)

• Type: Vercel Serverless Function (Edge Function)
• Purpose: Tracks component downloads and stores them in Supabase
• Runtime: Node.js with ES Modules
• HTTP Method: POST
• URL: https://www.aitmpl.com/api/track-download-supabase

Environment Variables Required:

• SUPABASE_URL - Your Supabase project URL
• SUPABASE_SERVICE_ROLE_KEY - Supabase service role key (with write permissions)

Request Payload:

{
  "type": "agent",
  "name": "frontend-developer",
  "path": "agents/development/frontend-developer",
  "category": "development",
  "cliVersion": "1.20.2"
}

Response (Success):

{
  "success": true,
  "message": "Download tracked successfully",
  "data": {
    "type": "agent",
    "name": "frontend-developer",
    "timestamp": "2025-10-12T13:00:00.000Z"
  }
}

Response (Error):

{
  "error": "Internal server error",
  "message": "Failed to track download"
}

Database Tables:

• component_downloads - Individual download records
• download_stats - Aggregated statistics

Called by: cli-tool/src/tracking-service.js when components are installed

---

3. package.json (Dependencies)

• Type: NPM package configuration
• Purpose: Defines dependencies for serverless functions
• Key Dependencies:
  • @supabase/supabase-js - Supabase client library
  • @vercel/postgres - PostgreSQL client for Vercel

---

🚀 Deployment Process

Prerequisites

1. Ensure environment variables are set in Vercel dashboard:
   • SUPABASE_URL
   • SUPABASE_SERVICE_ROLE_KEY

Automatic Deployment

When you push to the main branch, Vercel automatically:

1. Detects changes in /docs/
2. Installs dependencies from /docs/api/package.json
3. Deploys serverless functions from /docs/api/*.js
4. Serves static files from /docs/

Manual Deployment

# From project root
cd docs
vercel --prod

# Or using Vercel CLI
vercel deploy --prod

Testing After Deployment

# Test serverless function
curl -X POST https://www.aitmpl.com/api/track-download-supabase \
  -H "Content-Type: application/json" \
  -d '{"type":"agent","name":"test","path":"test","category":"test","cliVersion":"1.0.0"}'

# Test static file
curl https://www.aitmpl.com/api/agents.json

---

🔧 Troubleshooting

Issue: 404 Error on API Endpoint

Symptom: /api/track-download-supabase returns 404

Possible Causes:

1. File not in /docs/api/ directory
2. File has incorrect export format
3. Vercel environment variables not set
4. Deploy not completed

Solution:

# Verify file exists
ls -la docs/api/track-download-supabase.js

# Check Vercel logs
vercel logs [deployment-url]

# Redeploy
vercel --prod

Issue: Function Times Out

Symptom: Request takes too long and times out

Possible Causes:

1. Supabase connection issues
2. Database performance problems
3. Network latency

Solution:

• Check Supabase status dashboard
• Verify database indexes exist
• Review function timeout settings in Vercel

Issue: Data Not Saving

Symptom: API returns 200 but data doesn't appear in Supabase

Possible Causes:

1. Wrong environment variables
2. Insufficient permissions on service role key
3. Table schema mismatch

Solution:

// Enable debug mode in tracking-service.js
process.env.CCT_DEBUG = 'true'

// Check logs in Vercel dashboard

---

📊 Monitoring

Vercel Analytics

• View function execution logs in Vercel dashboard
• Monitor function performance and errors
• Track deployment history

Supabase Analytics

• View download statistics in Supabase dashboard
• Query component_downloads table directly
• Use download_stats for aggregated data

CLI Debug Mode

Enable debug mode to see tracking requests:

export CCT_DEBUG=true
npx claude-code-templates@latest --agent frontend-developer

---

🔄 Maintenance

Updating the Serverless Function

1. Edit /api/track-download-supabase.js (source of truth)
2. Copy changes to /docs/api/track-download-supabase.js
3. Test locally if possible
4. Commit and push changes
5. Verify deployment in Vercel dashboard

Updating Dependencies

1. Edit /docs/api/package.json
2. Commit changes
3. Vercel will automatically install on next deployment

Syncing Files

If you update /api/track-download-supabase.js, remember to sync:

cp api/track-download-supabase.js docs/api/
cp api/package.json docs/api/
git add docs/api/
git commit -m "Sync API changes to docs/api"

---

📝 Best Practices

1. Keep Both Directories in Sync: If you modify /api/, copy changes to /docs/api/
2. Test Before Deploy: Use debug mode to test tracking locally
3. Monitor Logs: Check Vercel logs after deployment
4. Version Control: Always commit both directories together
5. Environment Variables: Never commit sensitive keys

---

🔗 Related Files

• /vercel.json - Vercel configuration (defines outputDirectory: "docs")
• /cli-tool/src/tracking-service.js - Client-side tracking implementation
• /generate_components_json.py - Generates agents.json
• /api/ - Original API directory (keep as source of truth)

---

📞 Support

If you encounter issues with the API:

1. Check Vercel deployment logs
2. Verify environment variables in Vercel dashboard
3. Test endpoints manually with curl
4. Review Supabase logs for database errors
5. Enable debug mode in CLI for detailed tracking logs

---

Last Updated: October 12, 2025 Maintained by: Claude Code Templates Team