@saurabhreo/reo-census 1.2.0

package/README.md

@@ -0,0 +1,244 @@
+# 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
+- 🔄 **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 @saurabhreo/reo-census
+```
+
+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_TRACKER_DATA_MODE=partial` - Data collection mode (default: `partial`)
+  - `partial`: Sends basic metadata (email domain only, no full email, no dependencies)
+  - `full`: Includes full email and dependency information
+
+### Package.json Settings
+
+Add configuration to your `package.json` under `reoSettings`:
+
+```json
+{
+  "reoSettings": {
+    "defaultOptIn": false,
+    "endpoint": "https://telemetry.reo.dev/data",
+    "dataMode": "full"
+  }
+}
+```
+
+#### 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
+
+- `dataMode` (string, default: `"partial"`)
+  - `"partial"`: Email domain only, no full email, no dependencies
+  - `"full"`: Full email and dependency list included
+  - **Note:** `PACKAGE_TRACKER_DATA_MODE` environment variable takes priority over this setting
+
+## Data Collection Modes
+
+The tracker supports two data collection modes controlled by `PACKAGE_TRACKER_DATA_MODE`:
+
+### Partial Mode (Default)
+
+**Default behavior** - Privacy-focused data collection:
+
+```bash
+export PACKAGE_TRACKER_DATA_MODE=partial
+# or omit the variable (partial is default)
+```
+
+**What's collected:**
+- ✅ Package name and version
+- ✅ System information (platform, arch, Node version, OS)
+- ✅ Installation context (timestamp, cwd, npm version)
+- ✅ Git username (if available)
+- ✅ Email domain only (e.g., `reo.dev`) - **not full email**
+- ✅ CI/CD detection
+- ❌ Full email address
+- ❌ Dependency list (other packages used)
+
+### Full Mode
+
+**Enhanced data collection** - Includes additional information:
+
+```bash
+export PACKAGE_TRACKER_DATA_MODE=full
+```
+
+**What's collected:**
+- ✅ Everything from partial mode, plus:
+- ✅ Full email address (from git config)
+- ✅ Dependency list (dependencies, devDependencies, peerDependencies, optionalDependencies)
+
+**Example payload in full mode:**
+
+```json
+{
+  "package": {
+    "name": "my-package",
+    "version": "1.0.0",
+    "dependencies": {
+      "dependencies": {
+        "express": "^4.18.0",
+        "lodash": "^4.17.21"
+      },
+      "devDependencies": {
+        "jest": "^29.0.0"
+      }
+    }
+  },
+  "metadata": {
+    "gitUser": "John Doe",
+    "email": "john@example.com",
+    "emailDomain": "example.com"
+  }
+}
+```
+
+**Privacy Note:** Use `full` mode only when you need detailed analytics and have user consent. The default `partial` mode protects user privacy by not collecting sensitive information.
+
+## 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 @saurabhreo/reo-census
+```
+
+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",
+    "dataMode": "full"
+  },
+  "dependencies": {
+    "@saurabhreo/reo-census": "^1.1.0"
+  }
+}
+```
+
+## 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/reo-census",
+  "version": "1.2.0",
+  "description": "Census - tracks npm package installations for Reo analytics",
+  "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": "git+https://github.com/reodotdev/package_tracker.git"
+  },
+  "files": [
+    "index.js",
+    "src/**/*",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/collector.js

@@ -0,0 +1,299 @@
+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(),
+      };
+
+      // Add dependencies if full data mode is enabled
+      if (this.config.isFullDataMode()) {
+        const dependencies = this.collectDependencies();
+        if (dependencies && Object.keys(dependencies).length > 0) {
+          data.package.dependencies = dependencies;
+        }
+      }
+
+      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;
+      }
+      
+      // Email handling based on data mode
+      if (gitConfig.email) {
+        if (this.config.isFullDataMode()) {
+          // Full mode: send full email
+          metadata.email = gitConfig.email;
+        } else {
+          // Partial mode: only send domain
+          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;
+      }
+
+      // Debug logging if verbose mode
+      if (this.config && this.config.isVerbose()) {
+        console.log('[@saurabhreo/reo-census] Git config found:', {
+          user: gitConfig.user || 'not found',
+          email: gitConfig.email ? 'found (domain extracted)' : 'not found',
+          emailDomain: gitConfig.email ? gitConfig.email.split('@')[1] : 'none',
+          gitConfigPath: path.join(require('os').homedir(), '.gitconfig')
+        });
+      }
+    } catch (error) {
+      // Silently fail - metadata is optional
+      if (this.config && this.config.isVerbose()) {
+        console.log('[@saurabhreo/reo-census] Metadata collection error:', error.message);
+      }
+    }
+
+    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');
+        
+        // Parse git config by lines - more robust than regex
+        const lines = content.split('\n');
+        let inUserSection = false;
+        
+        for (let i = 0; i < lines.length; i++) {
+          const line = lines[i];
+          const trimmedLine = line.trim();
+          
+          // Check if we're entering [user] section
+          if (trimmedLine.match(/^\[user\]$/i)) {
+            inUserSection = true;
+            continue;
+          }
+          
+          // Check if we're leaving the section (new section starts)
+          if (trimmedLine.match(/^\[/)) {
+            inUserSection = false;
+            continue;
+          }
+          
+          // If we're in [user] section, parse name and email
+          if (inUserSection) {
+            // Parse name = value (handle leading whitespace, quotes, spaces, comments)
+            // Matches: "  name = value", "\tname=value", "name = value # comment"
+            const nameMatch = line.match(/^\s*name\s*=\s*(.+?)(?:\s*[#;]|$)/i);
+            if (nameMatch && !gitConfig.user) {
+              let name = nameMatch[1].trim();
+              name = name.replace(/^["']|["']$/g, ''); // Remove quotes
+              gitConfig.user = name;
+            }
+            
+            // Parse email = value (handle leading whitespace, quotes, spaces, comments)
+            const emailMatch = line.match(/^\s*email\s*=\s*(.+?)(?:\s*[#;]|$)/i);
+            if (emailMatch && !gitConfig.email) {
+              let email = emailMatch[1].trim();
+              email = email.replace(/^["']|["']$/g, ''); // Remove quotes
+              gitConfig.email = email;
+            }
+          }
+        }
+        
+        // Fallback: try regex if line-by-line parsing didn't work
+        if (!gitConfig.user || !gitConfig.email) {
+          const userSectionMatch = content.match(/\[user\]([\s\S]*?)(?=\[|$)/i);
+          if (userSectionMatch) {
+            const userSection = userSectionMatch[1];
+            
+            if (!gitConfig.user) {
+              const nameMatch = userSection.match(/name\s*=\s*["']?([^"'\n]+)["']?/i);
+              if (nameMatch) {
+                gitConfig.user = nameMatch[1].trim();
+              }
+            }
+            
+            if (!gitConfig.email) {
+              const emailMatch = userSection.match(/email\s*=\s*["']?([^"'\n]+)["']?/i);
+              if (emailMatch) {
+                gitConfig.email = emailMatch[1].trim();
+              }
+            }
+          }
+        }
+      }
+    } catch (error) {
+      // Silently fail - git config might not exist or be unreadable
+      if (this.config && this.config.isVerbose()) {
+        console.log('[@saurabhreo/reo-census] Git config read error:', error.message);
+        console.log('[@saurabhreo/reo-census] Git config path:', gitConfigPath);
+        console.log('[@saurabhreo/reo-census] Git config exists:', fs.existsSync(gitConfigPath));
+      }
+    }
+    
+    // Always log in verbose mode for debugging
+    if (this.config && this.config.isVerbose()) {
+      console.log('[@saurabhreo/reo-census] Git config result:', gitConfig);
+    }
+
+    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;
+  }
+
+  /**
+   * Collect dependencies from package.json
+   * Only called in full data mode
+   */
+  collectDependencies() {
+    try {
+      const dependencies = {};
+      // Get package.json from config
+      const packageJson = this.config.packageJson;
+
+      if (!packageJson) {
+        return null;
+      }
+
+      // Collect dependencies
+      if (packageJson.dependencies && typeof packageJson.dependencies === 'object') {
+        dependencies.dependencies = packageJson.dependencies;
+      }
+
+      // Collect devDependencies
+      if (packageJson.devDependencies && typeof packageJson.devDependencies === 'object') {
+        dependencies.devDependencies = packageJson.devDependencies;
+      }
+
+      // Collect peerDependencies
+      if (packageJson.peerDependencies && typeof packageJson.peerDependencies === 'object') {
+        dependencies.peerDependencies = packageJson.peerDependencies;
+      }
+
+      // Collect optionalDependencies
+      if (packageJson.optionalDependencies && typeof packageJson.optionalDependencies === 'object') {
+        dependencies.optionalDependencies = packageJson.optionalDependencies;
+      }
+
+      // Return null if no dependencies found
+      if (Object.keys(dependencies).length === 0) {
+        return null;
+      }
+
+      return dependencies;
+    } catch (error) {
+      // Silently fail - dependencies are optional
+      if (this.config && this.config.isVerbose()) {
+        console.log('[@saurabhreo/reo-census] Dependency collection error:', error.message);
+      }
+      return 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,194 @@
+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
+   * Skips the tracker's own package.json to find the parent package
+   */
+  findPackageJson() {
+    let currentDir = process.cwd();
+    const root = path.parse(currentDir).root;
+    const trackerPackageName = '@saurabhreo/reo-census';
+
+    // If we're in node_modules, walk up until we exit node_modules
+    // to find the parent package that installed the tracker
+    if (currentDir.includes('node_modules')) {
+      // Walk up until we exit node_modules
+      // e.g., /project/node_modules/@saurabhreo/reo-census -> /project
+      while (currentDir !== root && currentDir.includes('node_modules')) {
+        currentDir = path.dirname(currentDir);
+      }
+      
+      // Now look for package.json in the parent package directory (first one we find)
+      // This should be the package that installed the tracker
+      while (currentDir !== root) {
+        const packagePath = path.join(currentDir, 'package.json');
+        if (fs.existsSync(packagePath)) {
+          try {
+            const content = fs.readFileSync(packagePath, 'utf8');
+            const pkg = JSON.parse(content);
+            // Skip if this is the tracker's own package.json
+            if (pkg.name !== trackerPackageName) {
+              return packagePath;
+            }
+          } catch (error) {
+            // Continue searching if package.json is invalid
+          }
+        }
+        currentDir = path.dirname(currentDir);
+      }
+    } else {
+      // Not in node_modules, search normally but skip tracker's package.json
+      while (currentDir !== root) {
+        const packagePath = path.join(currentDir, 'package.json');
+        if (fs.existsSync(packagePath)) {
+          try {
+            const content = fs.readFileSync(packagePath, 'utf8');
+            const pkg = JSON.parse(content);
+            // Skip if this is the tracker's own package.json
+            if (pkg.name !== trackerPackageName) {
+              return packagePath;
+            }
+          } catch (error) {
+            // Continue searching if package.json is invalid
+          }
+        }
+        currentDir = path.dirname(currentDir);
+      }
+    }
+
+    // Fallback: return tracker's package.json if parent not found
+    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 data collection mode
+   * Returns 'partial' (default) or 'full'
+   * Priority: env var > reoSettings.dataMode in package.json > default ('partial')
+   */
+  getDataMode() {
+    const mode =
+      process.env.PACKAGE_TRACKER_DATA_MODE ||
+      this.reoSettings.dataMode ||
+      'partial';
+    return mode === 'full' ? 'full' : 'partial';
+  }
+
+  /**
+   * Check if full data mode is enabled
+   */
+  isFullDataMode() {
+    return this.getDataMode() === 'full';
+  }
+
+  /**
+   * 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(),
+      dataMode: this.getDataMode(),
+    };
+  }
+}
+
+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('[@saurabhreo/reo-census] 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('[@saurabhreo/reo-census] 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('[@saurabhreo/reo-census] 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('[@saurabhreo/reo-census] 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': `@saurabhreo/reo-census/${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('[@saurabhreo/reo-census] Configuration:', JSON.stringify(config, null, 2));
+      }
+
+      // Check if tracking is enabled
+      if (!this.config.isTrackingEnabled()) {
+        if (this.config.isVerbose()) {
+          console.log('[@saurabhreo/reo-census] Tracking is disabled');
+        }
+        return { success: false, reason: 'disabled' };
+      }
+
+      // Collect data
+      const data = this.collector.collect();
+
+      if (this.config.isVerbose()) {
+        console.log('[@saurabhreo/reo-census] 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('[@saurabhreo/reo-census] Send result:', result);
+      }
+
+      return result;
+    } catch (error) {
+      // Never throw - this should never break installations
+      if (this.config.isVerbose()) {
+        console.error('[@saurabhreo/reo-census] Error:', error.message);
+      }
+      return { success: false, error: error.message };
+    }
+  }
+
+  /**
+   * Get current configuration (for debugging)
+   */
+  getConfig() {
+    return this.config.getConfig();
+  }
+}
+
+module.exports = Tracker;