Skip to main content

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/json
string
Client user agent string (automatically captured)

Body Parameters

string
required
Component type. Must be one of:
  • agent
  • command
  • setting
  • hook
  • mcp
  • skill
  • template
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 success
string
Confirmation message
object
Download information
string
Component type
string
Component name
string
ISO 8601 timestamp of the download

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

Note: The 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 onConflict on (component_type, component_name)

Metadata Captured

The endpoint automatically captures:
string
Extracted from headers in order:
  1. x-forwarded-for (first IP)
  2. x-real-ip
  3. Connection remote address
  4. Fallback: 127.0.0.1
string
Extracted from Vercel geo header x-vercel-ip-country
string
From user-agent request header

Rate 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:
Preflight 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)