@saurabhreo/package-tracker 1.0.0

package/README.md

@@ -0,0 +1,242 @@
+# Package Tracker
+
+A lightweight npm package tracking utility similar to Reo. Tracks package installations and sends analytics data to your backend service.
+
+## Features
+
+- 🚀 **Zero Runtime Overhead** - Only runs during installation, never at runtime
+- 🔒 **Privacy-First** - Respects opt-out mechanisms and user preferences
+- ⚡ **Non-Blocking** - Never interrupts package installation
+- 📊 **Rich Data Collection** - System info, OS stats, package metadata, and more
+- 🔄 **Retry Logic** - Automatic retries with exponential backoff
+- 🎛️ **Configurable** - Environment variables and package.json settings
+
+## Installation
+
+Add this package as a dependency to any npm package you want to track:
+
+```bash
+npm install --save @package-tracker/tracker
+```
+
+Once installed, the tracker will automatically run after `npm install` completes.
+
+## Configuration
+
+### Environment Variables
+
+- `PACKAGE_TRACKER_ANALYTICS=false` - Disable tracking (opt-out)
+- `PACKAGE_TRACKER_ANALYTICS=true` - Enable tracking (for opt-in mode)
+- `PACKAGE_TRACKER_VERBOSE=true` - Enable verbose logging
+- `PACKAGE_TRACKER_ENDPOINT=https://telemetry.reo.dev/data` - Set tracking endpoint URL
+
+### Package.json Settings
+
+Add configuration to your `package.json`:
+
+```json
+{
+  "reoSettings": {
+    "defaultOptIn": false,
+    "endpoint": "https://telemetry.reo.dev/data"
+  }
+}
+```
+
+#### Settings
+
+- `defaultOptIn` (boolean, default: `true`)
+  - `true`: Tracking enabled by default (opt-out mode)
+  - `false`: Tracking disabled by default (opt-in mode)
+
+- `endpoint` (string, optional)
+  - Custom endpoint URL for tracking data
+  - Falls back to `PACKAGE_TRACKER_ENDPOINT` environment variable
+
+## How It Works
+
+1. **Postinstall Hook**: The tracker runs automatically via npm's `postinstall` script
+2. **Data Collection**: Gathers system info, package metadata, and installation context
+3. **Telemetry Sending**: Sends data to your configured endpoint via HTTP POST
+4. **Non-Blocking**: All operations are asynchronous and won't block installations
+
+## Data Collected
+
+The tracker collects the following information:
+
+### Package Information
+- Package name and version
+- Installation type (dependency, global, top-level)
+
+### System Information
+- Platform (darwin, linux, win32, etc.)
+- Architecture (x64, arm64, etc.)
+- Node.js version
+- OS type and release
+- CPU count
+
+### Installation Context
+- Timestamp
+- Current working directory
+- npm version
+- Node environment
+
+### Optional Metadata
+- Git user information (if available)
+- Email domain (for company detection)
+- CI/CD environment detection
+
+## Privacy & Opt-Out
+
+### For Package Authors
+
+To make tracking opt-in (disabled by default):
+
+```json
+{
+  "reoSettings": {
+    "defaultOptIn": false
+  }
+}
+```
+
+### For End Users
+
+Users can opt-out by setting:
+
+```bash
+export PACKAGE_TRACKER_ANALYTICS=false
+npm install
+```
+
+Or on Windows:
+
+```cmd
+set PACKAGE_TRACKER_ANALYTICS=false
+npm install
+```
+
+## Integration Example
+
+### Basic Integration
+
+1. Add the tracker to your package:
+
+```bash
+npm install --save @package-tracker/tracker
+```
+
+2. Configure your endpoint in `package.json`:
+
+```json
+{
+  "reoSettings": {
+    "endpoint": "https://telemetry.reo.dev/data"
+  }
+}
+```
+
+3. Publish your package - tracking will work automatically!
+
+### Advanced Configuration
+
+```json
+{
+  "name": "my-package",
+  "version": "1.0.0",
+  "reoSettings": {
+    "defaultOptIn": false,
+    "endpoint": "https://telemetry.reo.dev/data"
+  },
+  "dependencies": {
+    "@package-tracker/tracker": "^1.0.0"
+  }
+}
+```
+
+## Backend API Requirements
+
+Your backend endpoint should:
+
+1. Accept POST requests with JSON payload
+2. Return 2xx status codes for success
+3. Handle the following payload structure:
+
+```json
+{
+  "package": {
+    "name": "package-name",
+    "version": "1.0.0"
+  },
+  "system": {
+    "platform": "darwin",
+    "arch": "x64",
+    "nodeVersion": "v18.0.0",
+    "osType": "Darwin",
+    "osRelease": "21.0.0",
+    "osPlatform": "darwin",
+    "cpuCount": 8
+  },
+  "installation": {
+    "timestamp": "2026-02-08T12:00:00.000Z",
+    "cwd": "/path/to/project",
+    "isTopLevel": false,
+    "npmVersion": "9.0.0",
+    "nodeEnv": "production"
+  },
+  "metadata": {
+    "emailDomain": "example.com",
+    "ci": [{"GITHUB_ACTIONS": "GitHub Actions"}]
+  }
+}
+```
+
+## Development
+
+### Testing
+
+See [TESTING.md](./TESTING.md) for comprehensive testing guide.
+
+**Quick Test:**
+
+```bash
+# Run test suite
+npm test
+
+# Start mock server for testing
+npm run test:server
+
+# Test directly with verbose output
+PACKAGE_TRACKER_VERBOSE=true \
+PACKAGE_TRACKER_ENDPOINT=https://httpbin.org/post \
+node index.js
+```
+
+### Testing Locally
+
+1. Set verbose mode:
+```bash
+export PACKAGE_TRACKER_VERBOSE=true
+```
+
+2. Test with a mock endpoint or your backend:
+```bash
+export PACKAGE_TRACKER_ENDPOINT=https://telemetry.reo.dev/data
+npm install
+```
+
+### Debugging
+
+Enable verbose logging to see what data is being collected and sent:
+
+```bash
+PACKAGE_TRACKER_VERBOSE=true npm install
+```
+
+## License
+
+MIT
+
+## Similar Projects
+
+This package is inspired by [@reo/reo](https://www.npmjs.com/package/@reo/reo) and provides similar functionality for custom backend services.

package/index.js

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+
+/**
+ * Entry point for package tracker
+ * This file is executed when the postinstall script runs
+ */
+
+const Tracker = require('./src/tracker');
+
+// Run tracker asynchronously with a maximum timeout
+// This ensures it never blocks the installation process
+const tracker = new Tracker();
+
+// Maximum time to wait before exiting (10 seconds)
+const MAX_WAIT_TIME = 10000;
+
+// Execute tracking with timeout protection
+const trackingPromise = tracker.track().catch(() => {
+  // Silently handle any errors - never break installations
+});
+
+// Race between tracking completion and maximum wait time
+Promise.race([
+  trackingPromise,
+  new Promise((resolve) => setTimeout(resolve, MAX_WAIT_TIME)),
+]).finally(() => {
+  // Exit after tracking completes or timeout, ensuring we don't hang
+  process.exit(0);
+});

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@saurabhreo/package-tracker",
+  "version": "1.0.0",
+  "description": "Package tracking utility similar to Reo - tracks npm package installations",
+  "main": "index.js",
+  "scripts": {
+    "postinstall": "node index.js",
+    "test": "node test.js",
+    "test:server": "node test-mock-server.js",
+    "prepublishOnly": "npm test",
+    "publish:patch": "npm version patch && npm publish --access public",
+    "publish:minor": "npm version minor && npm publish --access public",
+    "publish:major": "npm version major && npm publish --access public"
+  },
+  "keywords": [
+    "analytics",
+    "tracking",
+    "npm",
+    "package-analytics",
+    "telemetry"
+  ],
+  "author": "Saurabh <saurabh@reo.dev>",
+  "license": "MIT",
+  "engines": {
+    "node": ">=12.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/reodotdev/package_tracker.git"
+  },
+  "files": [
+    "index.js",
+    "src/**/*",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/collector.js

@@ -0,0 +1,160 @@
+const os = require('os');
+const path = require('path');
+const fs = require('fs');
+
+/**
+ * Data collector for package tracking
+ * Gathers system information, package metadata, and installation context
+ */
+class Collector {
+  constructor(config) {
+    this.config = config;
+  }
+
+  /**
+   * Collect all tracking data
+   */
+  collect() {
+    try {
+      const data = {
+        // Package information
+        package: {
+          name: this.config.getPackageName(),
+          version: this.config.getPackageVersion(),
+        },
+
+        // System information
+        system: {
+          platform: process.platform,
+          arch: process.arch,
+          nodeVersion: process.version,
+          osType: os.type(),
+          osRelease: os.release(),
+          osPlatform: os.platform(),
+          cpuCount: os.cpus().length,
+        },
+
+        // Installation context
+        installation: {
+          timestamp: new Date().toISOString(),
+          cwd: process.cwd(),
+          isTopLevel: this.config.isTopLevelInstall(),
+          npmVersion: process.env.npm_version || 'unknown',
+          nodeEnv: process.env.NODE_ENV || 'unknown',
+        },
+
+        // Optional: Company/user information
+        metadata: this.collectMetadata(),
+      };
+
+      return data;
+    } catch (error) {
+      // Return minimal data if collection fails
+      return {
+        package: {
+          name: this.config.getPackageName(),
+          version: this.config.getPackageVersion(),
+        },
+        error: 'Collection failed',
+        timestamp: new Date().toISOString(),
+      };
+    }
+  }
+
+  /**
+   * Collect optional metadata (company info, git info, etc.)
+   */
+  collectMetadata() {
+    const metadata = {};
+
+    try {
+      // Try to get git user info
+      const gitConfig = this.getGitConfig();
+      if (gitConfig.user) {
+        metadata.gitUser = gitConfig.user;
+      }
+      if (gitConfig.email) {
+        // Only include domain, not full email for privacy
+        const emailDomain = gitConfig.email.split('@')[1];
+        if (emailDomain) {
+          metadata.emailDomain = emailDomain;
+        }
+      }
+
+      // Try to detect CI/CD environment
+      const ciInfo = this.detectCI();
+      if (ciInfo) {
+        metadata.ci = ciInfo;
+      }
+
+      // Try to get npm user info (if available)
+      const npmUser = process.env.npm_config_user;
+      if (npmUser) {
+        metadata.npmUser = npmUser;
+      }
+    } catch (error) {
+      // Silently fail - metadata is optional
+    }
+
+    return metadata;
+  }
+
+  /**
+   * Read git config to get user information
+   */
+  getGitConfig() {
+    const gitConfig = {};
+    const gitConfigPath = path.join(os.homedir(), '.gitconfig');
+
+    try {
+      if (fs.existsSync(gitConfigPath)) {
+        const content = fs.readFileSync(gitConfigPath, 'utf8');
+        
+        // Simple parsing of git config
+        const userMatch = content.match(/\[user\]\s+name\s*=\s*(.+)/i);
+        const emailMatch = content.match(/\[user\]\s+email\s*=\s*(.+)/i);
+
+        if (userMatch) {
+          gitConfig.user = userMatch[1].trim();
+        }
+        if (emailMatch) {
+          gitConfig.email = emailMatch[1].trim();
+        }
+      }
+    } catch (error) {
+      // Silently fail
+    }
+
+    return gitConfig;
+  }
+
+  /**
+   * Detect CI/CD environment
+   */
+  detectCI() {
+    const ciEnvs = {
+      CI: process.env.CI,
+      GITHUB_ACTIONS: process.env.GITHUB_ACTIONS ? 'GitHub Actions' : null,
+      GITLAB_CI: process.env.GITLAB_CI ? 'GitLab CI' : null,
+      JENKINS: process.env.JENKINS_URL ? 'Jenkins' : null,
+      TRAVIS: process.env.TRAVIS ? 'Travis CI' : null,
+      CIRCLE_CI: process.env.CIRCLE_CI ? 'CircleCI' : null,
+      BITBUCKET_BUILD_NUMBER: process.env.BITBUCKET_BUILD_NUMBER ? 'Bitbucket Pipelines' : null,
+    };
+
+    const detected = Object.entries(ciEnvs)
+      .filter(([_, value]) => value !== null && value !== undefined)
+      .map(([key, value]) => ({ [key]: value }));
+
+    return detected.length > 0 ? detected : null;
+  }
+
+  /**
+   * Format data for sending (can be overridden for custom formatting)
+   */
+  format(data) {
+    return JSON.stringify(data);
+  }
+}
+
+module.exports = Collector;

package/src/config.js

@@ -0,0 +1,132 @@
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Configuration handler for package tracker
+ * Reads environment variables and package.json settings
+ */
+class Config {
+  constructor() {
+    this.packageJsonPath = this.findPackageJson();
+    this.packageJson = this.loadPackageJson();
+    this.reoSettings = this.packageJson?.reoSettings || {};
+  }
+
+  /**
+   * Find package.json by walking up the directory tree
+   */
+  findPackageJson() {
+    let currentDir = process.cwd();
+    const root = path.parse(currentDir).root;
+
+    while (currentDir !== root) {
+      const packagePath = path.join(currentDir, 'package.json');
+      if (fs.existsSync(packagePath)) {
+        return packagePath;
+      }
+      currentDir = path.dirname(currentDir);
+    }
+
+    // Fallback to current directory
+    return path.join(process.cwd(), 'package.json');
+  }
+
+  /**
+   * Load package.json content
+   */
+  loadPackageJson() {
+    try {
+      if (fs.existsSync(this.packageJsonPath)) {
+        const content = fs.readFileSync(this.packageJsonPath, 'utf8');
+        return JSON.parse(content);
+      }
+    } catch (error) {
+      // Silently fail - package.json might not exist or be invalid
+    }
+    return null;
+  }
+
+  /**
+   * Check if tracking is enabled
+   * Respects environment variable and package.json settings
+   */
+  isTrackingEnabled() {
+    // Check environment variable first (highest priority)
+    const envOptOut = process.env.PACKAGE_TRACKER_ANALYTICS === 'false';
+    if (envOptOut) {
+      return false;
+    }
+
+    // Check if defaultOptIn is set to false in package.json
+    if (this.reoSettings.defaultOptIn === false) {
+      // In opt-in mode, check if explicitly enabled
+      return process.env.PACKAGE_TRACKER_ANALYTICS === 'true';
+    }
+
+    // Default: opt-out mode (enabled by default)
+    return true;
+  }
+
+  /**
+   * Check if verbose logging is enabled
+   */
+  isVerbose() {
+    return process.env.PACKAGE_TRACKER_VERBOSE === 'true';
+  }
+
+  /**
+   * Get tracking endpoint URL
+   * Can be configured via environment variable or package.json
+   */
+  getEndpointUrl() {
+    return (
+      process.env.PACKAGE_TRACKER_ENDPOINT ||
+      this.reoSettings.endpoint ||
+      'https://telemetry.reo.dev/data' // Default endpoint
+    );
+  }
+
+  /**
+   * Get package name from package.json
+   */
+  getPackageName() {
+    return this.packageJson?.name || 'unknown';
+  }
+
+  /**
+   * Get package version from package.json
+   */
+  getPackageVersion() {
+    return this.packageJson?.version || 'unknown';
+  }
+
+  /**
+   * Check if this is a top-level installation
+   * Reo only tracks when installed as dependency or globally
+   */
+  isTopLevelInstall() {
+    // Check if we're in node_modules (dependency) or global install
+    const cwd = process.cwd();
+    const isInNodeModules = cwd.includes('node_modules');
+    const isGlobal = process.env.npm_config_global === 'true';
+    
+    // If not in node_modules and not global, it's likely top-level
+    return !isInNodeModules && !isGlobal;
+  }
+
+  /**
+   * Get all configuration for logging
+   */
+  getConfig() {
+    return {
+      enabled: this.isTrackingEnabled(),
+      verbose: this.isVerbose(),
+      endpoint: this.getEndpointUrl(),
+      packageName: this.getPackageName(),
+      packageVersion: this.getPackageVersion(),
+      isTopLevel: this.isTopLevelInstall(),
+    };
+  }
+}
+
+module.exports = Config;

package/src/sender.js

@@ -0,0 +1,143 @@
+const https = require('https');
+const http = require('http');
+
+/**
+ * HTTP client for sending tracking data
+ * Implements retry logic, timeouts, and error handling
+ */
+class Sender {
+  constructor(config) {
+    this.config = config;
+    this.endpoint = config.getEndpointUrl();
+    this.maxRetries = 3;
+    this.timeout = 5000; // 5 seconds per request
+    this.maxTotalTimeout = 10000; // 10 seconds total maximum (including retries)
+  }
+
+  /**
+   * Send tracking data to the endpoint
+   * Non-blocking and best-effort (never throws)
+   */
+  async send(data) {
+    if (!this.config.isTrackingEnabled()) {
+      if (this.config.isVerbose()) {
+        console.log('[package-tracker] Tracking disabled');
+      }
+      return { success: false, reason: 'disabled' };
+    }
+
+    // Don't track top-level installations by default (like Reo)
+    if (this.config.isTopLevelInstall()) {
+      if (this.config.isVerbose()) {
+        console.log('[package-tracker] Skipping top-level installation');
+      }
+      return { success: false, reason: 'top-level-install' };
+    }
+
+    const payload = typeof data === 'string' ? data : JSON.stringify(data);
+
+    if (this.config.isVerbose()) {
+      console.log('[package-tracker] Sending data:', payload);
+    }
+
+    try {
+      // Enforce maximum total timeout to prevent hanging
+      const timeoutPromise = this.sleep(this.maxTotalTimeout).then(() => {
+        throw new Error('Maximum timeout exceeded');
+      });
+
+      const result = await Promise.race([
+        this.sendWithRetry(payload),
+        timeoutPromise,
+      ]);
+      return result;
+    } catch (error) {
+      // Never throw - this is best-effort
+      if (this.config.isVerbose()) {
+        console.error('[package-tracker] Failed to send:', error.message);
+      }
+      return { success: false, error: error.message };
+    }
+  }
+
+  /**
+   * Send with retry logic
+   */
+  async sendWithRetry(payload, retryCount = 0) {
+    try {
+      const result = await this.makeRequest(payload);
+      return { success: true, statusCode: result.statusCode };
+    } catch (error) {
+      if (retryCount < this.maxRetries) {
+        // Exponential backoff: 1s, 2s, 4s
+        const delay = Math.pow(2, retryCount) * 1000;
+        await this.sleep(delay);
+        return this.sendWithRetry(payload, retryCount + 1);
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Make HTTP/HTTPS request
+   */
+  makeRequest(payload) {
+    return new Promise((resolve, reject) => {
+      const url = new URL(this.endpoint);
+      const isHttps = url.protocol === 'https:';
+      const client = isHttps ? https : http;
+
+      const options = {
+        hostname: url.hostname,
+        port: url.port || (isHttps ? 443 : 80),
+        path: url.pathname + url.search,
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'Content-Length': Buffer.byteLength(payload),
+          'User-Agent': `package-tracker/${this.config.getPackageVersion()}`,
+        },
+        timeout: this.timeout,
+      };
+
+      const req = client.request(options, (res) => {
+        let data = '';
+
+        res.on('data', (chunk) => {
+          data += chunk;
+        });
+
+        res.on('end', () => {
+          if (res.statusCode >= 200 && res.statusCode < 300) {
+            resolve({ statusCode: res.statusCode, data });
+          } else {
+            reject(
+              new Error(`Request failed with status ${res.statusCode}`)
+            );
+          }
+        });
+      });
+
+      req.on('error', (error) => {
+        reject(error);
+      });
+
+      req.on('timeout', () => {
+        req.destroy();
+        reject(new Error('Request timeout'));
+      });
+
+      req.write(payload);
+      req.end();
+    });
+  }
+
+  /**
+   * Sleep utility for retry delays
+   */
+  sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+}
+
+module.exports = Sender;

package/src/tracker.js

@@ -0,0 +1,69 @@
+const Config = require('./config');
+const Collector = require('./collector');
+const Sender = require('./sender');
+
+/**
+ * Main tracker orchestrator
+ * Coordinates configuration, data collection, and sending
+ */
+class Tracker {
+  constructor() {
+    this.config = new Config();
+    this.collector = new Collector(this.config);
+    this.sender = new Sender(this.config);
+  }
+
+  /**
+   * Run the tracking process
+   * This is the main entry point
+   */
+  async track() {
+    try {
+      // Log tracking status if verbose
+      if (this.config.isVerbose()) {
+        const config = this.config.getConfig();
+        console.log('[package-tracker] Configuration:', JSON.stringify(config, null, 2));
+      }
+
+      // Check if tracking is enabled
+      if (!this.config.isTrackingEnabled()) {
+        if (this.config.isVerbose()) {
+          console.log('[package-tracker] Tracking is disabled');
+        }
+        return { success: false, reason: 'disabled' };
+      }
+
+      // Collect data
+      const data = this.collector.collect();
+
+      if (this.config.isVerbose()) {
+        console.log('[package-tracker] Collected data:', JSON.stringify(data, null, 2));
+      }
+
+      // Send data (non-blocking, best-effort)
+      const result = await this.sender.send(data);
+
+      // Log result if verbose
+      if (this.config.isVerbose()) {
+        console.log('[package-tracker] Send result:', result);
+      }
+
+      return result;
+    } catch (error) {
+      // Never throw - this should never break installations
+      if (this.config.isVerbose()) {
+        console.error('[package-tracker] Error:', error.message);
+      }
+      return { success: false, error: error.message };
+    }
+  }
+
+  /**
+   * Get current configuration (for debugging)
+   */
+  getConfig() {
+    return this.config.getConfig();
+  }
+}
+
+module.exports = Tracker;