Endpoint
POST/api/track-download-supabase
Tracks component downloads for analytics. This endpoint is called automatically by the CLI whenever a user installs a component.
Request
Headers
string
required
Must be
application/jsonstring
Client user agent string (automatically captured)
Body Parameters
string
required
Component type. Must be one of:
agentcommandsettinghookmcpskilltemplate
string
required
Component name. Maximum 255 characters.
string
Component path in the repository
string
Component category (e.g., “development-team”, “automation”)
string
Version of the CLI tool used for installation
Example Request
Response
Success Response (200 OK)
boolean
Always
true on successstring
Confirmation message
object
Example Success Response
Error Responses
400 Bad Request - Invalid Component Type
400 Bad Request - Missing Required Fields
400 Bad Request - Name Too Long
405 Method Not Allowed
500 Internal Server Error
details field is only included in development mode.
Data Storage
Download events are stored in two Supabase tables:component_downloads
Stores individual download records with:- Component metadata (type, name, path, category)
- User information (IP address, country, user agent)
- CLI version
- Timestamp
download_stats
Aggregated statistics using upsert:- Total downloads per component
- Last download timestamp
- Automatically updated via
onConflicton(component_type, component_name)
Metadata Captured
The endpoint automatically captures:string
Extracted from headers in order:
x-forwarded-for(first IP)x-real-ip- Connection remote address
- Fallback:
127.0.0.1
string
Extracted from Vercel geo header
x-vercel-ip-countrystring
From
user-agent request headerRate Limiting
No explicit rate limits are enforced, but requests are subject to:- Vercel serverless function execution limits (10s timeout)
- Supabase connection pool limits
CORS Support
The endpoint supports CORS with:OPTIONS requests return 200 OK.
Notes
- The endpoint never fails the user’s installation if tracking fails
- Stats update errors are logged but don’t return 500 responses
- All timestamps are stored in ISO 8601 format
- The endpoint is idempotent (duplicate downloads are recorded separately)