@scope-analytics/browser 0.0.4

package/README.md

@@ -0,0 +1,109 @@
+# Scope Analytics
+
+Zero-code analytics with AI-powered insights. Install analytics in under 5 minutes without modifying your application code.
+
+## Installation
+
+```bash
+# Run after building your application
+npx @scope-analytics/browser install --key YOUR_PUBLIC_KEY
+
+# Or use environment variable
+export SCOPE_PUBLIC_KEY=your_public_key
+npx @scope-analytics/browser install
+```
+
+## How it Works
+
+Scope Analytics modifies your built HTML files to inject our lightweight SDK. This approach:
+- ✅ Works with any framework or build tool
+- ✅ No code changes required
+- ✅ Automatic tracking of all user interactions
+- ✅ Compatible with all major hosting platforms
+
+## Platform-Specific Setup
+
+### Vercel
+```json
+// vercel.json
+{
+  "buildCommand": "npm run build && npx @scope-analytics/browser install"
+}
+```
+
+### Netlify
+```toml
+# netlify.toml
+[build]
+command = "npm run build && npx @scope-analytics/browser install"
+```
+
+### Render
+Set build command: `npm run build && npx @scope-analytics/browser install`
+
+### Next.js
+```json
+// package.json
+{
+  "scripts": {
+    "build": "next build && npx @scope-analytics/browser install --dir .next"
+  }
+}
+```
+
+## Commands
+
+### Install
+```bash
+npx @scope-analytics/browser install [options]
+
+Options:
+  -k, --key <apiKey>      Your Scope Analytics public key
+  -d, --dir <directory>   Build output directory (default: dist)
+  -e, --endpoint <url>    Custom API endpoint
+  --no-api-tracking       Disable API call tracking
+  --debug                 Enable debug mode
+```
+
+### Uninstall
+```bash
+npx @scope-analytics/browser uninstall [options]
+
+Options:
+  -d, --dir <directory>   Build output directory (default: dist)
+```
+
+### Validate
+```bash
+npx @scope-analytics/browser validate [options]
+
+Options:
+  -d, --dir <directory>   Build output directory (default: dist)
+```
+
+## What Gets Tracked
+
+- 📊 Page views and navigation
+- 🖱️ Clicks and interactions
+- 📜 Scroll behavior and reading time
+- ⏱️ Performance metrics
+- 🔗 API calls (optional)
+- ❌ Errors and exceptions
+
+## Features
+
+- **AI-Powered Insights**: Ask questions in natural language
+- **Automatic Tracking**: No manual event setup required
+- **Privacy-First**: No personal data collection
+- **Lightweight**: < 30KB gzipped
+- **Real-Time**: See events as they happen
+
+## Support
+
+- Documentation: Coming soon at https://scopeai.dev
+- Email: Contact via https://scopeai.dev
+- Issues: Please report issues via our website
+
+## License
+
+MIT

package/bin/scope-analytics.js

@@ -0,0 +1,103 @@
+#!/usr/bin/env node
+
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { install } from '../src/install.js';
+import { uninstall } from '../src/uninstall.js';
+import { validate } from '../src/validate.js';
+
+const program = new Command();
+
+program
+  .name('scope-analytics')
+  .description('Scope Analytics - Build-time integration for zero-code analytics')
+  .version('0.0.4');
+
+program
+  .command('install')
+  .description('Install Scope Analytics SDK into your built application')
+  .option('-k, --key <apiKey>', 'Your Scope Analytics public key (or use SCOPE_PUBLIC_KEY env var)')
+  .option('-d, --dir <directory>', 'Build output directory', 'dist')
+  .option('-e, --endpoint <url>', 'Custom API endpoint', 'https://api.scopeai.dev')
+  .option('--no-api-tracking', 'Disable API call tracking')
+  .option('--channel <channel>', 'SDK channel (v1, beta, stable)', 'v1')
+  .option('--sdk-url <url>', 'Custom SDK URL (overrides channel)')
+  .option('--debug', 'Enable debug mode')
+  .action(async (options) => {
+    try {
+      const apiKey = options.key || process.env.SCOPE_PUBLIC_KEY;
+      
+      if (!apiKey) {
+        console.error(chalk.red('Error: API key is required'));
+        console.error(chalk.yellow('Please provide it via --key flag or SCOPE_PUBLIC_KEY environment variable'));
+        process.exit(1);
+      }
+
+      console.log(chalk.cyan('🚀 Installing Scope Analytics...'));
+      
+      await install({
+        apiKey,
+        buildDir: options.dir,
+        endpoint: options.endpoint,
+        trackApiCalls: options.apiTracking,
+        channel: options.channel,
+        sdkUrl: options.sdkUrl,
+        debug: options.debug
+      });
+
+      console.log(chalk.green('✅ Scope Analytics installed successfully!'));
+      console.log(chalk.gray('Your application is now tracking analytics.'));
+    } catch (error) {
+      console.error(chalk.red('Installation failed:'), error.message);
+      if (options.debug) {
+        console.error(error);
+      }
+      process.exit(1);
+    }
+  });
+
+program
+  .command('uninstall')
+  .description('Remove Scope Analytics SDK from your application')
+  .option('-d, --dir <directory>', 'Build output directory', 'dist')
+  .action(async (options) => {
+    try {
+      console.log(chalk.cyan('🗑️  Uninstalling Scope Analytics...'));
+      
+      await uninstall({
+        buildDir: options.dir
+      });
+
+      console.log(chalk.green('✅ Scope Analytics uninstalled successfully'));
+    } catch (error) {
+      console.error(chalk.red('Uninstall failed:'), error.message);
+      process.exit(1);
+    }
+  });
+
+program
+  .command('validate')
+  .description('Validate that Scope Analytics is properly installed')
+  .option('-d, --dir <directory>', 'Build output directory', 'dist')
+  .action(async (options) => {
+    try {
+      console.log(chalk.cyan('🔍 Validating Scope Analytics installation...'));
+      
+      const result = await validate({
+        buildDir: options.dir
+      });
+
+      if (result.valid) {
+        console.log(chalk.green('✅ Scope Analytics is properly installed'));
+        console.log(chalk.gray(`Found in ${result.files.length} HTML files`));
+      } else {
+        console.log(chalk.yellow('⚠️  Scope Analytics is not installed'));
+        console.log(chalk.gray('Run "npx @scope-analytics/browser install" to add analytics to your application'));
+      }
+    } catch (error) {
+      console.error(chalk.red('Validation failed:'), error.message);
+      process.exit(1);
+    }
+  });
+
+program.parse();

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@scope-analytics/browser",
+  "version": "0.0.4",
+  "description": "Build-time integration for Scope Analytics - Zero-code analytics with AI insights",
+  "main": "src/index.js",
+  "type": "module",
+  "bin": {
+    "scope-analytics": "bin/scope-analytics.js"
+  },
+  "scripts": {},
+  "keywords": [
+    "analytics",
+    "scope",
+    "tracking",
+    "ai",
+    "build-tool"
+  ],
+  "author": "Scope AI",
+  "license": "MIT",
+  "homepage": "https://scopeai.dev",
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "commander": "^11.1.0",
+    "glob": "^10.3.10"
+  },
+  "engines": {
+    "node": ">=14.0.0"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "README.md"
+  ]
+}

package/src/index.js

@@ -0,0 +1,7 @@
+export { install } from './install.js';
+export { uninstall } from './uninstall.js';
+export { validate } from './validate.js';
+
+// Platform-specific helpers
+export { detectPlatform } from './platforms/detect.js';
+export { getInstallInstructions } from './platforms/instructions.js';

package/src/install.js

@@ -0,0 +1,158 @@
+import fs from 'fs/promises';
+import path from 'path';
+import { glob } from 'glob';
+import chalk from 'chalk';
+
+// Determine SDK URL based on environment
+function getSDKUrl(options) {
+  // Allow explicit SDK URL override
+  if (options.sdkUrl) {
+    return options.sdkUrl;
+  }
+  
+  // Check for channel preference
+  const channel = options.channel || process.env.SCOPE_SDK_CHANNEL || 'v1';
+  const validChannels = ['v1', 'beta', 'stable'];
+  
+  if (validChannels.includes(channel)) {
+    return `https://cdn.scopeai.dev/${channel}/sdk.js`;
+  }
+  
+  // Default to stable (v1) with cache-busting version
+  const version = '0.0.2'; // Update this with each SDK release
+  return `https://cdn.scopeai.dev/v1/sdk.js?v=${version}`;
+}
+
+export async function install(options) {
+  const {
+    apiKey,
+    buildDir = 'dist',
+    endpoint = 'https://api.scopeai.dev',
+    trackApiCalls = true,
+    debug = false
+  } = options;
+
+  // Verify build directory exists
+  try {
+    await fs.access(buildDir);
+  } catch (error) {
+    throw new Error(`Build directory "${buildDir}" does not exist. Please build your application first.`);
+  }
+
+  // Find all HTML files
+  const htmlFiles = await glob(`${buildDir}/**/*.html`);
+  
+  if (htmlFiles.length === 0) {
+    throw new Error(`No HTML files found in "${buildDir}". Is this the correct build directory?`);
+  }
+
+  if (debug) {
+    console.log(chalk.gray(`Found ${htmlFiles.length} HTML files to process`));
+  }
+
+  let modifiedCount = 0;
+
+  // Process each HTML file
+  for (const filePath of htmlFiles) {
+    try {
+      let content = await fs.readFile(filePath, 'utf8');
+      
+      // Skip if already installed
+      if (content.includes('SCOPE_CONFIG') || content.includes('cdn.scopeai.dev/sdk.js')) {
+        if (debug) {
+          console.log(chalk.gray(`Skipping ${path.relative(buildDir, filePath)} (already installed)`));
+        }
+        continue;
+      }
+
+      // Create the injection script
+      const sdkUrl = getSDKUrl(options);
+      const injectionScript = createInjectionScript({
+        apiKey,
+        endpoint,
+        trackApiCalls,
+        sdkUrl
+      });
+
+      // Find the best injection point
+      const injectionPoint = findInjectionPoint(content);
+      
+      if (!injectionPoint) {
+        console.warn(chalk.yellow(`Warning: Could not find </body> or </html> tag in ${path.relative(buildDir, filePath)}`));
+        continue;
+      }
+
+      // Inject the script
+      content = content.slice(0, injectionPoint.index) + 
+                injectionScript + 
+                content.slice(injectionPoint.index);
+
+      // Write the modified content back
+      await fs.writeFile(filePath, content, 'utf8');
+      modifiedCount++;
+
+      if (debug) {
+        console.log(chalk.gray(`✓ Modified ${path.relative(buildDir, filePath)}`));
+      }
+    } catch (error) {
+      console.error(chalk.red(`Error processing ${filePath}:`), error.message);
+      throw error;
+    }
+  }
+
+  if (modifiedCount === 0) {
+    console.log(chalk.yellow('⚠️  No files were modified. Scope Analytics may already be installed.'));
+  } else {
+    console.log(chalk.green(`✓ Modified ${modifiedCount} HTML file${modifiedCount === 1 ? '' : 's'}`));
+  }
+
+  // Copy the SDK file if we're using a local version (for development)
+  if (process.env.SCOPE_DEV_MODE === 'true') {
+    await copyLocalSDK(buildDir);
+  }
+}
+
+function createInjectionScript({ apiKey, endpoint, trackApiCalls, sdkUrl }) {
+  // For the one-line install, we'll pass the public key as a URL parameter
+  const sdkUrlWithKey = `${sdkUrl}${sdkUrl.includes('?') ? '&' : '?'}token=${apiKey}`;
+  
+  return `
+<!-- Scope Analytics -->
+<script src="${sdkUrlWithKey}" async></script>
+<!-- End Scope Analytics -->
+`;
+}
+
+function findInjectionPoint(html) {
+  // Try to find </body> first
+  const bodyMatch = html.match(/<\/body>/i);
+  if (bodyMatch) {
+    return {
+      index: bodyMatch.index,
+      tag: '</body>'
+    };
+  }
+
+  // Fallback to </html>
+  const htmlMatch = html.match(/<\/html>/i);
+  if (htmlMatch) {
+    return {
+      index: htmlMatch.index,
+      tag: '</html>'
+    };
+  }
+
+  return null;
+}
+
+async function copyLocalSDK(buildDir) {
+  try {
+    const sdkSource = path.join(process.cwd(), '../../sdk-new/core/dist/scope-sdk.js');
+    const sdkDest = path.join(buildDir, 'scope-sdk.js');
+    
+    await fs.copyFile(sdkSource, sdkDest);
+    console.log(chalk.gray('✓ Copied local SDK for development'));
+  } catch (error) {
+    console.warn(chalk.yellow('Could not copy local SDK:', error.message));
+  }
+}

package/src/platforms/detect.js

@@ -0,0 +1,48 @@
+import fs from 'fs/promises';
+import path from 'path';
+
+export async function detectPlatform() {
+  const checks = [
+    { file: 'vercel.json', platform: 'vercel' },
+    { file: 'netlify.toml', platform: 'netlify' },
+    { file: 'render.yaml', platform: 'render' },
+    { file: 'railway.json', platform: 'railway' },
+    { file: '.dockerignore', platform: 'docker' },
+    { file: 'app.json', platform: 'heroku' }
+  ];
+
+  // Check for platform-specific files
+  for (const check of checks) {
+    try {
+      await fs.access(check.file);
+      return check.platform;
+    } catch {
+      // File doesn't exist, continue
+    }
+  }
+
+  // Check package.json for framework clues
+  try {
+    const packageJson = JSON.parse(await fs.readFile('package.json', 'utf8'));
+    
+    if (packageJson.dependencies) {
+      if (packageJson.dependencies.next) return 'nextjs';
+      if (packageJson.dependencies.gatsby) return 'gatsby';
+      if (packageJson.dependencies.nuxt) return 'nuxt';
+      if (packageJson.dependencies['@angular/core']) return 'angular';
+      if (packageJson.dependencies.vue) return 'vue';
+      if (packageJson.dependencies.react) return 'react';
+    }
+
+    // Check scripts for build tools
+    if (packageJson.scripts) {
+      if (packageJson.scripts.build?.includes('vite')) return 'vite';
+      if (packageJson.scripts.build?.includes('webpack')) return 'webpack';
+      if (packageJson.scripts.build?.includes('parcel')) return 'parcel';
+    }
+  } catch {
+    // No package.json or error reading it
+  }
+
+  return 'generic';
+}

package/src/platforms/instructions.js

@@ -0,0 +1,71 @@
+export function getInstallInstructions(platform, apiKey) {
+  const instructions = {
+    vercel: {
+      name: 'Vercel',
+      steps: [
+        '1. Add SCOPE_PUBLIC_KEY to your environment variables in Vercel dashboard',
+        '2. Update your build command in vercel.json or dashboard:',
+        '   "buildCommand": "npm run build && npx @scope-analytics/browser install"',
+        '3. Deploy your application'
+      ]
+    },
+    netlify: {
+      name: 'Netlify',
+      steps: [
+        '1. Add SCOPE_PUBLIC_KEY to your environment variables in Netlify dashboard',
+        '2. Update your netlify.toml:',
+        '   [build]',
+        '   command = "npm run build && npx @scope-analytics/browser install"',
+        '3. Deploy your application'
+      ]
+    },
+    render: {
+      name: 'Render',
+      steps: [
+        '1. Add SCOPE_PUBLIC_KEY to your environment variables in Render dashboard',
+        '2. Update your build command:',
+        '   Build Command: npm run build && npx @scope-analytics/browser install',
+        '3. Deploy your application'
+      ]
+    },
+    railway: {
+      name: 'Railway',
+      steps: [
+        '1. Add SCOPE_PUBLIC_KEY to your environment variables in Railway dashboard',
+        '2. Update your build command in railway.json:',
+        '   "build": "npm run build && npx @scope-analytics/browser install"',
+        '3. Deploy your application'
+      ]
+    },
+    nextjs: {
+      name: 'Next.js',
+      steps: [
+        '1. Add SCOPE_PUBLIC_KEY to your .env.local or deployment environment',
+        '2. Update your package.json scripts:',
+        '   "build": "next build && npx @scope-analytics/browser install --dir .next"',
+        '3. Deploy as usual'
+      ]
+    },
+    vite: {
+      name: 'Vite',
+      steps: [
+        '1. Add SCOPE_PUBLIC_KEY to your environment',
+        '2. Update your package.json scripts:',
+        '   "build": "vite build && npx @scope-analytics/browser install"',
+        '3. Deploy the dist folder'
+      ]
+    },
+    generic: {
+      name: 'Generic Setup',
+      steps: [
+        '1. Set your public key:',
+        `   export SCOPE_PUBLIC_KEY="${apiKey || 'your-public-key'}"`,
+        '2. After building your app, run:',
+        '   npx @scope-analytics/browser install',
+        '3. Deploy your built files'
+      ]
+    }
+  };
+
+  return instructions[platform] || instructions.generic;
+}

package/src/uninstall.js

@@ -0,0 +1,68 @@
+import fs from 'fs/promises';
+import path from 'path';
+import { glob } from 'glob';
+import chalk from 'chalk';
+
+export async function uninstall(options) {
+  const { buildDir = 'dist' } = options;
+
+  // Verify build directory exists
+  try {
+    await fs.access(buildDir);
+  } catch (error) {
+    throw new Error(`Build directory "${buildDir}" does not exist.`);
+  }
+
+  // Find all HTML files
+  const htmlFiles = await glob(`${buildDir}/**/*.html`);
+  
+  if (htmlFiles.length === 0) {
+    console.log(chalk.yellow('No HTML files found to uninstall from'));
+    return;
+  }
+
+  let modifiedCount = 0;
+
+  // Process each HTML file
+  for (const filePath of htmlFiles) {
+    try {
+      let content = await fs.readFile(filePath, 'utf8');
+      const originalLength = content.length;
+
+      // Remove Scope Analytics scripts
+      content = removeScopeAnalytics(content);
+
+      // Only write if content changed
+      if (content.length !== originalLength) {
+        await fs.writeFile(filePath, content, 'utf8');
+        modifiedCount++;
+      }
+    } catch (error) {
+      console.error(chalk.red(`Error processing ${filePath}:`), error.message);
+      throw error;
+    }
+  }
+
+  console.log(chalk.green(`✓ Removed from ${modifiedCount} HTML file${modifiedCount === 1 ? '' : 's'}`));
+
+  // Remove local SDK file if exists
+  try {
+    const localSDK = path.join(buildDir, 'scope-sdk.js');
+    await fs.unlink(localSDK);
+    console.log(chalk.gray('✓ Removed local SDK file'));
+  } catch (error) {
+    // Ignore if file doesn't exist
+  }
+}
+
+function removeScopeAnalytics(html) {
+  // Remove the entire Scope Analytics section
+  const scopePattern = /<!-- Scope Analytics -->[\s\S]*?<!-- End Scope Analytics -->\n?/g;
+  html = html.replace(scopePattern, '');
+
+  // Also remove any standalone references (in case the comments were removed)
+  html = html.replace(/<script[^>]*>[\s\S]*?SCOPE_CONFIG[\s\S]*?<\/script>\n?/g, '');
+  html = html.replace(/<script[^>]*src="[^"]*cdn\.scopeai\.dev\/sdk\.js"[^>]*><\/script>\n?/g, '');
+
+  return html;
+}

package/src/validate.js

@@ -0,0 +1,48 @@
+import fs from 'fs/promises';
+import path from 'path';
+import { glob } from 'glob';
+
+export async function validate(options) {
+  const { buildDir = 'dist' } = options;
+
+  // Verify build directory exists
+  try {
+    await fs.access(buildDir);
+  } catch (error) {
+    throw new Error(`Build directory "${buildDir}" does not exist.`);
+  }
+
+  // Find all HTML files
+  const htmlFiles = await glob(`${buildDir}/**/*.html`);
+  
+  if (htmlFiles.length === 0) {
+    return {
+      valid: false,
+      files: [],
+      message: 'No HTML files found in build directory'
+    };
+  }
+
+  const installedFiles = [];
+
+  // Check each HTML file
+  for (const filePath of htmlFiles) {
+    try {
+      const content = await fs.readFile(filePath, 'utf8');
+      
+      // Check if Scope Analytics is installed
+      if (content.includes('SCOPE_CONFIG') && content.includes('cdn.scopeai.dev/sdk.js')) {
+        installedFiles.push(path.relative(buildDir, filePath));
+      }
+    } catch (error) {
+      console.error(`Error reading ${filePath}:`, error.message);
+    }
+  }
+
+  return {
+    valid: installedFiles.length > 0,
+    files: installedFiles,
+    totalFiles: htmlFiles.length,
+    coverage: (installedFiles.length / htmlFiles.length) * 100
+  };
+}