{"id":24366967,"url":"https://github.com/thisuxhq/track","last_synced_at":"2026-04-17T04:34:24.900Z","repository":{"id":273057386,"uuid":"918582529","full_name":"thisuxhq/track","owner":"thisuxhq","description":"A simple and powerful analytics API built with Cloudflare Workers, KV storage, and Hono.js. Track any kind of user events, calculate session durations, and get insights about user behavior.","archived":false,"fork":false,"pushed_at":"2025-01-18T10:14:33.000Z","size":22,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-09-05T11:55:21.507Z","etag":null,"topics":["analytics","analytics-tracking","cloudflare-kv","cloudflare-workers","honojs","thisux","typescript"],"latest_commit_sha":null,"homepage":"https://thisux.com","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/thisuxhq.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-01-18T10:09:01.000Z","updated_at":"2025-01-18T10:50:04.000Z","dependencies_parsed_at":null,"dependency_job_id":"6b96c5c2-a02f-4f0c-b1a6-ff7703929364","html_url":"https://github.com/thisuxhq/track","commit_stats":null,"previous_names":["thisuxhq/track"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/thisuxhq/track","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thisuxhq%2Ftrack","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thisuxhq%2Ftrack/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thisuxhq%2Ftrack/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thisuxhq%2Ftrack/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/thisuxhq","download_url":"https://codeload.github.com/thisuxhq/track/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thisuxhq%2Ftrack/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31915369,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-16T18:22:33.417Z","status":"online","status_checked_at":"2026-04-17T02:00:06.879Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["analytics","analytics-tracking","cloudflare-kv","cloudflare-workers","honojs","thisux","typescript"],"created_at":"2025-01-19T01:10:39.901Z","updated_at":"2026-04-17T04:34:24.894Z","avatar_url":"https://github.com/thisuxhq.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Analytics API Documentation\n\nA simple and powerful analytics API built with Cloudflare Workers, KV storage, and Hono.js. Track any kind of user events, calculate session durations, and get insights about user behavior.\n\n## 🚀 Quick Start\n\n1. Install the dependencies:\n```bash\nnpm install hono @hono/zod-validator zod\n```\n\n2. Set up your Cloudflare Worker:\n```bash\nnpm install -g wrangler\nwrangler login\n```\n\n3. Create a KV namespace:\n```bash\nwrangler kv:namespace create \"ANALYTICS_KV\"\n```\n\n4. Set up your configuration:\n```bash\n# Copy the example config\ncp wrangler.toml.example wrangler.toml\n\n# Update wrangler.toml with your KV namespace IDs and other settings\n```\n\nExample wrangler.toml structure:\n```toml\nname = \"analytics-api\"\nmain = \"src/index.ts\"\ncompatibility_date = \"2024-01-18\"\n\n[[kv_namespaces]]\nbinding = \"ANALYTICS_KV\"\nid = \"your-kv-namespace-id\"        # Replace with your production KV ID\npreview_id = \"your-preview-id\"     # Replace with your preview KV ID\n```\n\n5. Deploy:\n```bash\nwrangler deploy\n```\n\n## 📝 API Reference\n\n### Track Events (POST /track)\n\nUsed to log any type of event. Events are stored with metadata and automatically expire after 30 days.\n\n#### Example Request\n\n```http\nPOST /track\n\n{\n  \"event\": \"play\",\n  \"user_id\": \"user123\",\n  \"timestamp\": \"2025-01-18T14:30:00Z\",\n  \"metadata\": {\n    \"song_id\": \"song456\",\n    \"device\": \"mobile\",\n    \"platform\": \"ios\"\n  }\n}\n```\n\nResponse:\n```json\n{\n  \"status\": \"success\",\n  \"message\": \"Event logged.\"\n}\n```\n\n#### What You Need to Know About Tracking\n- `timestamp` is optional - defaults to server time\n- Future timestamps are automatically set to current server time\n- `metadata` is optional and limited to 4KB\n- If metadata exceeds 4KB, it's truncated with a warning\n- Each event is stored for 30 days\n- Events are automatically counted for metrics\n\n### Get Event Counts (GET /metrics)\n\nGet counts of different events over time, grouped by day, week, or month.\n\n```http\nGET /metrics?start_date=2025-01-01\u0026end_date=2025-01-31\u0026group_by=day\u0026user_id=user123\n```\n\nRequired parameters:\n- `start_date`: YYYY-MM-DD format\n- `end_date`: YYYY-MM-DD format\n\nOptional parameters:\n- `group_by`: \"day\" (default), \"week\", or \"month\"\n- `user_id`: Filter metrics for specific user\n\nResponse:\n```json\n{\n  \"status\": \"success\",\n  \"data\": [\n    {\n      \"date\": \"2025-01-01\",\n      \"play\": 24,\n      \"stop\": 22,\n      \"pause\": 5\n    }\n  ]\n}\n```\n\n### Get Session Data (GET /sessions)\n\nGet session statistics grouped by time period. Sessions are created from play/stop event pairs.\n\n```http\nGET /sessions?start_date=2025-01-01\u0026end_date=2025-01-31\u0026group_by=day\u0026user_id=user123\n```\n\nRequired parameters:\n- `start_date`: YYYY-MM-DD format\n- `end_date`: YYYY-MM-DD format\n\nOptional parameters:\n- `group_by`: \"day\" (default), \"week\", or \"month\"\n- `user_id`: Filter sessions for specific user\n\nResponse:\n```json\n{\n  \"status\": \"success\",\n  \"data\": [\n    {\n      \"date\": \"2025-01-01\",\n      \"totalDuration\": 7200,\n      \"sessionCount\": 15,\n      \"averageDuration\": 480\n    }\n  ]\n}\n```\n\n## 🤔 Common Questions and Edge Cases\n\n### What happens if...\n\n**The same user starts multiple sessions?**\n- Each play/stop pair creates a separate session\n- We match each stop event with the most recent play event for that user\n\n**A stop event comes without a play event?**\n- The stop event is logged but no session is created\n- This won't break anything, but won't show up in session stats\n\n**A play event never gets a stop event?**\n- The play event is logged but no session duration is calculated\n- These incomplete sessions won't appear in session stats\n\n**The timestamp is in the future?**\n- The event is logged but marked with the server time instead\n- A warning is added to the metadata\n\n**The metadata is really large?**\n- There's a 4KB limit on metadata size\n- If exceeded, the event is logged but metadata is truncated\n\n### Tips for Best Results\n\n1. Always use consistent user IDs for the same user\n2. Send events in real-time when possible\n3. Include relevant metadata that you might want to analyze later\n4. Use descriptive event names (like \"play\", \"pause\", \"skip\" instead of \"event1\", \"event2\")\n5. Keep metadata size reasonable (under 4KB)\n\n## 🔍 Example Use Cases\n\n### Music App\n```json\n// Track song play\nPOST /track\n{\n  \"event\": \"play\",\n  \"user_id\": \"user123\",\n  \"metadata\": {\n    \"song_id\": \"song456\",\n    \"playlist\": \"workout_mix\",\n    \"device\": \"iphone\"\n  }\n}\n\n// Track song completion\nPOST /track\n{\n  \"event\": \"complete\",\n  \"user_id\": \"user123\",\n  \"metadata\": {\n    \"song_id\": \"song456\",\n    \"listened_seconds\": 180\n  }\n}\n```\n\n### E-commerce Site\n```json\n// Track product view\nPOST /track\n{\n  \"event\": \"product_view\",\n  \"user_id\": \"user123\",\n  \"metadata\": {\n    \"product_id\": \"prod789\",\n    \"category\": \"electronics\",\n    \"price\": 299.99\n  }\n}\n\n// Track purchase\nPOST /track\n{\n  \"event\": \"purchase\",\n  \"user_id\": \"user123\",\n  \"metadata\": {\n    \"order_id\": \"order123\",\n    \"total\": 299.99,\n    \"items\": [\"prod789\"]\n  }\n}\n```\n\n## ⚠️ Error Handling\n\nAll errors follow this format:\n```json\n{\n  \"status\": \"error\",\n  \"message\": \"Description of what went wrong\"\n}\n```\n\nCommon error messages:\n- \"Failed to log event\"\n- \"Failed to fetch metrics\"\n- \"Failed to fetch session metrics\"\n- \"start_date and end_date are required\"\n- \"Invalid date format. Use YYYY-MM-DD\"\n\n## 🔒 Rate Limits and Security\n\n- Events expire after 30 days\n- Metadata size limit: 4KB\n- CORS is enabled for all origins\n- SSL/TLS is required for all API calls\n\nNeed help? Found a bug? Check our GitHub issues or contact work@thisux.com\n\n## 🧪 Testing\n\n### Curl Examples\n\nWe provide a shell script with curl examples for testing all endpoints:\n\n```bash\n# Make the script executable\nchmod +x examples.sh\n./examples.sh\n```\n\nThe script includes examples for:\n- Tracking play/stop events\n- Getting metrics with different time ranges\n- Testing session analytics\n- Testing error cases\n- Testing metadata size limits\n\n### Postman Collection\n\nFor easier testing, import our Postman collection:\n\n1. Download `analytics-api.postman_collection.json`\n2. Import into Postman\n3. Set your `baseUrl` variable in the collection variables\n4. Start testing!\n\nThe collection includes:\n- Track Events (play, stop, future timestamps, large metadata)\n- Get Metrics (daily, weekly, error cases)\n- Get Sessions (daily, weekly aggregation)\n\n## 👋 About Us\n\nThis repository is created by [ThisUX.com](https://thisux.com), a design studio specializing in building beautiful and functional apps. We combine technical excellence with stunning design to create exceptional user experiences.\n\nNeed help with your next project? [Schedule a 15-min call](https://cal.com/imsanju/15min) with us to discuss how we can help bring your vision to life.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthisuxhq%2Ftrack","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthisuxhq%2Ftrack","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthisuxhq%2Ftrack/lists"}