{"_id":"@1984vc/telemetry-todo","_rev":"2-f55be72b1b6b2dd131c7db80e2920e81","name":"@1984vc/telemetry-todo","dist-tags":{"latest":"1.1.0"},"versions":{"1.0.0":{"name":"@1984vc/telemetry-todo","version":"1.0.0","keywords":["todo","cli","typescript","telemetry","privacy","productivity","task-management","command-line"],"author":{"name":"1984 Ventures"},"license":"MIT","_id":"@1984vc/telemetry-todo@1.0.0","maintainers":[{"name":"mdp","email":"m@mdp.im"}],"homepage":"https://github.com/1984vc/telemetry-todo#readme","bugs":{"url":"https://github.com/1984vc/telemetry-todo/issues"},"bin":{"telemetry-todo":"dist/main.js"},"dist":{"shasum":"5bd3e3a5dba84fdc367f658753bc7d6ddd27a8d7","tarball":"https://registry.npmjs.org/@1984vc/telemetry-todo/-/telemetry-todo-1.0.0.tgz","fileCount":10,"integrity":"sha512-R4DwyLA2FPsmhYcRWIVapX1gb728uzeWqKNXYcd97lCDquygvTlxpT6etFcQBQuUiXm6WEnLNJK5Ha7p1Tu1ow==","signatures":[{"sig":"MEUCICqoyB6bzBSdCu6rvAFMzACWC9K2GQ1JIKuNYPciQYGiAiEAi9/17VCPtO+zPgy8o9IbNY4z7PyX8dmgFAa0pK0J5Ss=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":55703},"main":"dist/main.js","types":"./dist/main.d.ts","engines":{"node":">=18.0.0"},"gitHead":"79469100d860f2d0de0b1ed4ee6012c298d2a4a4","scripts":{"dev":"ts-node src/main.ts","build":"tsc","start":"node dist/main.js","prepublishOnly":"pnpm run build"},"_npmUser":{"name":"mdp","email":"m@mdp.im"},"repository":{"url":"git+https://github.com/1984vc/telemetry-todo.git","type":"git"},"_npmVersion":"11.4.2","description":"A privacy-first TypeScript CLI todo application with anonymous telemetry","directories":{},"_nodeVersion":"24.4.1","dependencies":{},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"ts-node":"^10.9.0","typescript":"^5.0.0","@types/node":"^20.0.0"},"_npmOperationalInternal":{"tmp":"tmp/telemetry-todo_1.0.0_1757703260282_0.3858021072297946","host":"s3://npm-registry-packages-npm-production"}},"1.1.0":{"name":"@1984vc/telemetry-todo","version":"1.1.0","description":"A privacy-first TypeScript CLI todo application with anonymous telemetry","main":"dist/main.js","bin":{"telemetry-todo":"dist/main.js"},"keywords":["todo","cli","typescript","telemetry","privacy","productivity","task-management","command-line"],"author":{"name":"1984 Ventures"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/1984vc/telemetry-todo.git"},"homepage":"https://github.com/1984vc/telemetry-todo#readme","bugs":{"url":"https://github.com/1984vc/telemetry-todo/issues"},"engines":{"node":">=18.0.0"},"publishConfig":{"access":"public"},"devDependencies":{"@types/node":"^20.0.0","ts-node":"^10.9.0","typescript":"^5.0.0"},"dependencies":{},"scripts":{"build":"tsc","dev":"ts-node src/main.ts","start":"node dist/main.js"},"_id":"@1984vc/telemetry-todo@1.1.0","types":"./dist/main.d.ts","_integrity":"sha512-58Vtujvu4dtKzdPqmeAsfvsrD8sUP82anWVWGZ3SjhI/zyR+EN87v0irIKTIMg0wPg2W47QUtWo/wC/bsCVVeQ==","_resolved":"/private/var/folders/f5/ptz9hkmj3wl4fz73b6blyjth0000gn/T/01fc1110adfce98a84016b2eb8f2d57f/1984vc-telemetry-todo-1.1.0.tgz","_from":"file:1984vc-telemetry-todo-1.1.0.tgz","_nodeVersion":"24.4.1","_npmVersion":"11.4.2","dist":{"integrity":"sha512-58Vtujvu4dtKzdPqmeAsfvsrD8sUP82anWVWGZ3SjhI/zyR+EN87v0irIKTIMg0wPg2W47QUtWo/wC/bsCVVeQ==","shasum":"102bd7762e23c8f3dbfddbc54fd2ab8de3e0e8d4","tarball":"https://registry.npmjs.org/@1984vc/telemetry-todo/-/telemetry-todo-1.1.0.tgz","fileCount":10,"unpackedSize":54698,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIGPTqrX1rI/3MR62ZeSWrzk/z52wTC0Vd+uH0Mu/AZzjAiEAoDwksT9y3gObEJTBvFYBWI6GTQ6DYLWmKHA+bSht+vo="}]},"_npmUser":{"name":"mdp","email":"m@mdp.im"},"directories":{},"maintainers":[{"name":"mdp","email":"m@mdp.im"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/telemetry-todo_1.1.0_1757963278066_0.2938631644312373"},"_hasShrinkwrap":false}},"time":{"created":"2025-09-12T18:54:20.182Z","modified":"2025-09-15T19:07:58.450Z","1.0.0":"2025-09-12T18:54:20.464Z","1.1.0":"2025-09-15T19:07:58.257Z"},"bugs":{"url":"https://github.com/1984vc/telemetry-todo/issues"},"author":{"name":"1984 Ventures"},"license":"MIT","homepage":"https://github.com/1984vc/telemetry-todo#readme","keywords":["todo","cli","typescript","telemetry","privacy","productivity","task-management","command-line"],"repository":{"type":"git","url":"git+https://github.com/1984vc/telemetry-todo.git"},"description":"A privacy-first TypeScript CLI todo application with anonymous telemetry","maintainers":[{"name":"mdp","email":"m@mdp.im"}],"readme":"# Privacy-Respecting Telemetry Demo CLI\n\nA comprehensive demonstration of how to implement **privacy-first telemetry** in a TypeScript CLI application. This todo application showcases best practices for collecting anonymous usage analytics while respecting user privacy and providing full transparency and control.\n\n## 🔒 Privacy-First Telemetry Features\n\nThis project demonstrates a complete privacy-respecting telemetry implementation with:\n\n- **🚫 Opt-out by Default**: Telemetry is enabled by default but can be disabled at any time\n- **🔧 Multiple Control Methods**: Environment variables, configuration files, and CLI commands\n- **📋 First-Run Disclosure**: Clear privacy notice before any data collection begins\n- **⚡ Non-blocking**: Telemetry never interrupts or slows down the user experience\n- **🛡️ Fail-Safe**: Silent failures ensure telemetry issues never break the application\n\n## 🎯 Demo Application Features\n\nThe underlying todo CLI includes:\n\n- ✅ Add, list, complete, and delete todos\n- 📊 View statistics and productivity graphs\n- 🎯 Interactive mode for continuous use\n- 💾 Persistent storage in `.todos.json`\n- 🎨 Colorful terminal output\n- 📅 Timestamps for task creation and completion\n\n## 🚀 Installation & Usage\n\n### NPM Installation\n\nInstall globally via npm:\n```bash\nnpm install -g @1984vc/telemetry-todo\n```\n\nOr run directly with npx (no installation required):\n```bash\nnpx @1984vc/telemetry-todo <command>\n```\n\n### Development Setup\n\n1. Clone the repository:\n   ```bash\n   git clone https://github.com/1984vc/telemetry-todo.git\n   cd telemetry-todo\n   ```\n\n2. Install dependencies:\n   ```bash\n   pnpm install\n   ```\n\n3. Build the project:\n   ```bash\n   pnpm run build\n   ```\n\n4. Run the CLI:\n   ```bash\n   node dist/main.js <command>\n   ```\n\n### Development Mode\n\nRun directly from TypeScript source:\n```bash\npnpm run dev <command>\n```\n\n## 📊 Telemetry Privacy Controls\n\n### Environment Variables\n\nControl telemetry through environment variables:\n\n```bash\n# Disable all telemetry (respects DO_NOT_TRACK standard)\nexport DO_NOT_TRACK=1\n\n# Application-specific telemetry control\nexport TELEMETRY_TODO_TELEMETRY=false\n\n# Enable telemetry explicitly\nexport TELEMETRY_TODO_TELEMETRY=true\n```\n\n### CLI Commands\n\nManage telemetry settings directly:\n\n```bash\n# Check current telemetry status\nnpx @1984vc/telemetry-todo telemetry status\n\n# Enable telemetry (with privacy disclosure)\nnpx @1984vc/telemetry-todo telemetry enable\n\n# Disable telemetry\nnpx @1984vc/telemetry-todo telemetry disable\n```\n\n### Configuration File\n\nSettings are stored in `.telemetry-config.json`:\n```json\n{\n  \"telemetryEnabled\": true,\n  \"firstRun\": true,\n  \"anonymousId\": \"4ff13743-eaeb-4f88-bb69-33fd3638c876\"\n}\n```\n\n## 🔍 Privacy-Compliant Data Collection\n\n### What We Track (Anonymously)\n\n- **Command Usage**: Which commands are executed (add, list, done, etc.)\n- **Performance Metrics**: Command execution times for optimization\n- **Error Events**: Anonymous error reporting for debugging\n- **System Info**: Platform and Node.js version (no personal data)\n- **Country-Level Geographic Data**: Country, continent, and timezone information only (for usage patterns)\n\n### What We DON'T Track\n\n- ❌ IP addresses (not stored or logged)\n- ❌ Personal information or identifiers\n- ❌ Todo content or user data\n- ❌ File paths or system details\n- ❌ Network information\n\n### Example Privacy-Compliant Payload\n\n```json\n{\n  \"api_key\": \"phc_IFaExYAUhS9kpVwk6zTBuk80H1D4Dr6QQdCfu\",\n  \"event\": \"command_executed\",\n  \"properties\": {\n    \"distinct_id\": \"4ff13743-eaeb-4f88-bb69-33fd3638c876\",\n    \"$referrer\": \"$direct\",\n    \"$referring_domain\": \"$direct\",\n    \"$lib\": \"telemetry-todo-cli\",\n    \"$lib_version\": \"1.0.0\",\n    \"$ip\": \"0.0.0.0\",\n    \"command\": \"add\",\n    \"platform\": \"darwin\",\n    \"node_version\": \"v24.4.1\"\n  }\n}\n```\n\n## 📝 Todo Commands\n\n### Basic Operations\n\n```bash\n# Add a todo\nnpx @1984vc/telemetry-todo add \"Your task here\"\n\n# List all todos\nnpx @1984vc/telemetry-todo list\n\n# Mark a todo as complete\nnpx @1984vc/telemetry-todo done <number>\n\n# Delete a todo\nnpx @1984vc/telemetry-todo delete <number>\n\n# Clear all todos\nnpx @1984vc/telemetry-todo clear\n```\n\n### Advanced Features\n\n```bash\n# View statistics\nnpx @1984vc/telemetry-todo stats\n\n# Interactive mode\nnpx @1984vc/telemetry-todo\n\n# Help\nnpx @1984vc/telemetry-todo help\n```\n\n## 🏗️ Technical Implementation\n\n### Architecture\n\n```\ntelemetry-todo/\n├── src/\n│   ├── main.ts          # Main CLI with telemetry integration\n│   └── telemetry.ts     # Privacy-first telemetry module\n├── dist/                # Compiled JavaScript output\n├── .telemetry-config.json # User telemetry preferences\n├── package.json         # Project configuration\n├── tsconfig.json        # TypeScript configuration\n└── README.md           # This documentation\n```\n\n### Key Technical Features\n\n- **Direct HTTPS Requests**: Uses Node.js built-in `https` module instead of heavy SDKs\n- **Timeout Protection**: 1-second timeout prevents hanging requests\n- **Non-blocking Execution**: `setImmediate()` ensures telemetry never blocks user operations\n- **Error Resilience**: Comprehensive error handling with silent failures\n- **TypeScript**: Full type safety and modern async/await patterns\n\n### PostHog Integration\n\nThis demo uses PostHog as the analytics backend with privacy-first configuration:\n\n- **Endpoint**: `https://us.i.posthog.com/capture/`\n- **No IP Address**: IP Adress is manually set to 0.0.0.0\n\n## �️ Privacy Compliance\n\nThis implementation follows privacy best practices:\n\n- **Transparent**: Full disclosure of data collection practices\n- **User Control**: Multiple ways to disable and control telemetry\n- **Data Minimization**: Only collects essential anonymous usage metrics\n\n## 🔧 Development & Testing\n\n### Building\n\n```bash\npnpm run build\n```\n\n### Testing Telemetry\n\n1. Check telemetry status (enabled by default):\n   ```bash\n   npx @1984vc/telemetry-todo telemetry status\n   ```\n\n2. Execute commands and observe privacy-compliant requests:\n   ```bash\n   npx @1984vc/telemetry-todo add \"Test task\"\n   npx @1984vc/telemetry-todo list\n   ```\n\n3. If needed, enable or disable telemetry:\n   ```bash\n   npx @1984vc/telemetry-todo telemetry enable\n   npx @1984vc/telemetry-todo telemetry disable\n   ```\n\n### Verifying Privacy Protection\n\nThe telemetry module logs request details (in development) showing:\n- No personal or identifying information\n\n## Learning Outcomes\n\nThis demo teaches:\n\n- **Privacy-First Design**: How to collect useful analytics while protecting user privacy\n- **Transparent Telemetry**: Best practices for user disclosure and consent\n- **Technical Implementation**: Direct HTTP requests, error handling, and non-blocking execution\n- **User Experience**: Ensuring telemetry never degrades application performance\n\n## 🤝 Contributing\n\nThis is a demonstration project showcasing privacy-respecting telemetry implementation. Feel free to:\n\n- Study the code for educational purposes\n- Adapt the privacy patterns for your own projects\n- Suggest improvements to the privacy implementation\n- Report any privacy concerns or issues\n\n## 📄 License\n\nThis project is provided as an educational demonstration of privacy-respecting telemetry implementation.\n\n---\n\n**🔒 Privacy Notice**: This application collects anonymous usage analytics by default but respects your privacy. No personal information, IP addresses, or location data is ever collected. You can disable telemetry at any time using the commands above or environment variables.\n","readmeFilename":"README.md"}