omnigate-ai 1.0.0

package/Dockerfile

@@ -0,0 +1,37 @@
+# ========================================================
+# Stage 1: Dependency builder
+# ========================================================
+FROM node:20-alpine AS builder
+
+WORKDIR /usr/src/app
+
+# Copy package descriptors
+COPY package*.json ./
+
+# Install only production dependencies cleanly
+RUN npm ci --only=production
+
+# ========================================================
+# Stage 2: Production runner
+# ========================================================
+FROM node:20-alpine AS runner
+
+# Set production environment variables
+ENV NODE_ENV=production
+ENV PORT=8080
+
+WORKDIR /usr/src/app
+
+# Copy production artifacts from builder and source code
+COPY package*.json ./
+COPY --from=builder /usr/src/app/node_modules ./node_modules
+COPY server.js ./
+
+# Run container as a non-root node user for container hardening
+USER node
+
+# Expose port
+EXPOSE 8080
+
+# Run the gateway server
+CMD ["node", "server.js"]

package/Omnigate AI.txt

@@ -0,0 +1,72 @@
+Product Requirement Document (PRD)
+Project: OmniGate AI (Enterprise AI Cost Gateway & Proxy)
+Document Version: 1.0
+Target Audience: Engineering Teams, AI Agencies, and B2B Development Shops
+1. Executive Summary & Product Goal
+1.1 Core Objective
+OmniGate AI is a self-hosted, privacy-first API gateway and proxy designed for software development agencies and enterprise teams building with Large Language Models (LLMs). The product solves the critical problem of "API Bill Shock"—unpredictable, skyrocketing AI costs caused by developer terminal tools (e.g., Claude Code), IDE extensions (e.g., Cursor, VS Code), and custom frontends that recursively send massive conversation histories and consume invisible "thinking/reasoning" tokens.
+1.2 Key Value Propositions
+Privacy-First Architecture: Self-hosted deployments mean sensitive codebases and client data never pass through a third-party SaaS infrastructure.
+Absolute Cost Transparency: Intercepts and logs precise, true token consumption (including hidden reasoning tokens) in real-time.
+Granular Governance: Allows agency administrators to set hard spending limits, track costs by project or developer, and prevent runaway automated agent loops.
+2. Problem Statement & Critical Roadblocks
+Through rigorous technical analysis, the following structural challenges have been identified and directly addressed in this specification:
+2.1 The Privacy Hurdle
+Agencies handling proprietary enterprise code or regulated data (e.g., healthcare, financial applications) will refuse to route API traffic through an external vendor's proxy.
+Solution: 100% decoupling of the data plane and the control plane. The proxy runs entirely within the client's network. Only metadata (token counts, timestamps, user IDs) is synchronized outwards.
+2.2 The "Invisible" Token Problem (Reasoning/Thinking)
+Modern tier-1 models (like OpenAI's o1/o3 or Anthropic's extended thinking models) do not expose thinking tokens inside the visible body of streamed text. Calculating costs by running a local tokenizer (like tiktoken) over raw text output will result in massive calculation deficits, causing the agency to underreport costs.
+Solution: Abandon localized text tokenization for streaming data. The gateway must modify incoming requests to force provider-side usage monitoring and extract the definitive billing token metadata directly from the final Server-Sent Events (SSE) payload chunks.
+3. Product Architecture & Technical Specifications
+  [ Developer Tool ] 
+  (VS Code, Claude Code, Terminal)
+         │
+         ▼ (Modified API Base URL)
+  ┌────────────────────────────────────────────────────────┐
+  │ CLIENT CLOUD INFRASTRUCTURE (Self-Hosted Docker)       │
+  │                                                        │
+  │   [ OmniGate Proxy Container ]                         │
+  │         │                                              │
+  │         ├─► 1. Modify Request & Forward Streaming  ────┼───► [ AI Provider API ]
+  │         │                                              │     (OpenAI, Anthropic)
+  │         └─► 2. Intercept Final SSE "Usage" Chunk        │
+  │                                                        │
+  └─────────────────────────┬──────────────────────────────┘
+                            │
+                            ▼ (Anonymized Telemetry Metadata Only)
+              [ Cloud Analytics Dashboard ]
+3.1 Core Proxy Service (Data Plane)
+Deployment Vector: Packaged exclusively as a lightweight Docker container (node:20-alpine) deployable via Docker Compose or Kubernetes on client infra.
+Multi-Provider Translation: Must support unified routing to major LLM providers:
+OpenAI (/v1/chat/completions)
+Anthropic (/v1/messages)
+Token Interception Protocol:
+For OpenAI Streams: The proxy must inspect incoming payloads and append/override "stream_options": {"include_usage": true}. The engine must actively listen for the final, non-text chunk containing the unified usage block.
+For Anthropic Streams: The engine must parse the message_start event for input tracking and compile the final message_delta/message_stop events to ensure output_tokens (inclusive of thinking blocks) are fully captured.
+3.2 Cloud Control Plane (SaaS Dashboard)
+Central Analytics Interface: A multi-tenant web platform where agency administrators log in to view charts, manage developer identities, and set budget thresholds.
+Telemetry Synchronization: The proxy container transmits single, lightweight, non-blocking telemetry payloads upon the completion of every successful API execution block.
+4. Functional Requirements
+4.1 Proxy & Security Configuration
+
+
+
+
+
+
+
+4.2 Tracking & Analytics
+
+4.3 Governance & Controls (B2B Features)
+
+5. Non-Functional Requirements (NFRs)
+Performance / Latency Overhead: The proxy stream evaluation loop must introduce less than 15ms of latency to the time-to-first-token (TTFT) and maintain zero perceptible drag during continuous token streaming.
+Resiliency: If connection drops occur between the self-hosted container and the centralized SaaS dashboard, the proxy must cache telemetry logs locally using an internal, ephemeral SQLite fallback mechanism and flush them once connectivity is restored. API traffic flowing to developers must never be blocked by external telemetry synchronization issues.
+6. Success Metrics & Future Milestones
+6.1 Phase 1 Success Metrics (MVP)
+Data Integrity: Zero discrepancy between the cost tracked on OmniGate and the end-of-month official bills generated by OpenAI/Anthropic.
+Infrastructure Churn: Less than 1% container crash frequency across diverse agency deployment environments.
+6.2 Future Enhancements (Phase 2 Roadmap)
+The Prompt Compressor: An intelligent token-reduction layer that scans prompt vectors within the proxy context and safely minifies data payloads to reduce active enterprise spend by 20–30% automatically.
+Semantic De-duplication: Internal caching of static context layers (like massive code files or dense system prompts) to prevent redundant upstream transmissions across adjacent development teams.
+Does this PRD provide the structural depth you need to begin technical execution, or would you like to expand the specifications on how the circuit breaker architecture detects runaway developer loops?

package/bin/omnigate.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import '../server.js';

package/docker-compose.yml

@@ -0,0 +1,16 @@
+version: '3.8'
+
+services:
+  gateway:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    container_name: omnigate-gateway
+    ports:
+      - "8080:8080"
+    environment:
+      - PORT=8080
+      - AGENCY_GATEWAY_KEY=stub-agency-key-for-local-testing
+      - OPENAI_API_KEY=your-openai-api-key-stub
+      - ANTHROPIC_API_KEY=your-anthropic-api-key-stub
+    restart: unless-stopped

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "omnigate-ai",
+  "version": "1.0.0",
+  "description": "Privacy-first, self-hosted LLM API Gateway and Proxy for tracking token usage.",
+  "main": "server.js",
+  "type": "module",
+  "bin": {
+    "omnigate": "./bin/omnigate.js"
+  },
+  "scripts": {
+    "start": "node server.js",
+    "dev": "node --watch server.js"
+  },
+  "keywords": [
+    "openai",
+    "anthropic",
+    "proxy",
+    "gateway",
+    "telemetry",
+    "token-counting",
+    "privacy-first"
+  ],
+  "author": "OmniGate AI Team",
+  "license": "MIT",
+  "dependencies": {
+    "cors": "^2.8.5",
+    "dotenv": "^16.4.5",
+    "express": "^4.19.2"
+  }
+}

package/payload-theme.json

@@ -0,0 +1 @@
+{"model":"deepseek-chat","messages":[{"role":"user","content":"Generate CSS for a dark/light theme toggle with a glassmorphism aesthetic. The dark theme should use deep purple-blue gradient background with glass cards. The light theme should use a soft off-white/light blue gradient with frosted glass cards. Both should feel elegant and polished. Include CSS variables for both themes."}],"stream":false}

package/proxy-helper.js

@@ -0,0 +1,60 @@
+/**
+ * This helper configures OmniGate proxy to work with DeepSeek/OpenAI
+ * and displays token usage information.
+ * 
+ * The proxy is already running on port 8080.
+ * Configure your API key via the dashboard at http://localhost:8080/dashboard/
+ * Gateway Key: stub-agency-key-for-local-testing
+ */
+
+const PROXY_URL = 'http://localhost:8080';
+
+// Pricing reference (from the dashboard)
+const PRICING = {
+  'gpt-4o': { in: 5.00, out: 15.00 },
+  'gpt-4o-mini': { in: 0.15, out: 0.60 },
+  'deepseek-chat': { in: 0.27, out: 1.10 },
+  'claude-3-5-sonnet-20241022': { in: 3.00, out: 15.00 },
+  'default': { in: 2.00, out: 10.00 }
+};
+
+export function calculateCost(model, inTokens, outTokens) {
+  const rates = PRICING[model] || PRICING['default'];
+  return (inTokens / 1000000) * rates.in + (outTokens / 1000000) * rates.out;
+}
+
+export async function getTelemetry() {
+  const res = await fetch(`${PROXY_URL}/api/telemetry`);
+  return res.json();
+}
+
+export async function getConfig() {
+  const res = await fetch(`${PROXY_URL}/api/config`, {
+    headers: { 'X-Gateway-Key': 'stub-agency-key-for-local-testing' }
+  });
+  return res.json();
+}
+
+console.log('\n╔══════════════════════════════════════════════════════════╗');
+console.log('║   🚪 OmniGate Proxy Helper                              ║');
+console.log('║                                                        ║');
+console.log('║   1. Open http://localhost:8080/dashboard/ in browser  ║');
+console.log('║   2. Enter Gateway Key: stub-agency-key-for-local-testing ║');
+console.log('║   3. Paste your API key and Save                       ║');
+console.log('║   4. Come back here and I will send test requests       ║');
+console.log('║      through the proxy so you see them on dashboard    ║');
+console.log('╚══════════════════════════════════════════════════════════╝\n');
+
+// Check current config status
+const config = await getConfig();
+console.log('Current proxy config:');
+console.log(`  OpenAI URL: ${config.openaiApiUrl}`);
+console.log(`  API Key set: ${config.openaiApiKey ? '✅ Yes' : '❌ No'}`);
+console.log(`  Gateway Key: ${config.agencyGatewayKey}\n`);
+
+if (!config.openaiApiKey) {
+  console.log('⚠️  No API key configured yet.');
+  console.log('➡️  Go to http://localhost:8080/dashboard/ and enter your key.\n');
+} else {
+  console.log('✅ API key is configured! Ready to route requests through proxy.\n');
+}

package/public/app.js

@@ -0,0 +1,432 @@
+document.addEventListener('DOMContentLoaded', () => {
+  // Constants for generic pricing estimates (per 1M tokens)
+  const PRICING = {
+    'gpt-4o': { in: 5.00, out: 15.00 },
+    'claude-3-5-sonnet-20241022': { in: 3.00, out: 15.00 },
+    'default': { in: 2.00, out: 10.00 } // fallback
+  };
+
+  // State
+  let totalTokens = 0;
+  let totalInputTokens = 0;
+  let totalOutputTokens = 0;
+  let totalCost = 0.0;
+  let totalRequests = 0;
+
+  // DOM Elements
+  const elTotalTokens = document.getElementById('total-tokens');
+  const elInputTokens = document.getElementById('input-tokens');
+  const elOutputTokens = document.getElementById('output-tokens');
+  
+  const elTotalCost = document.getElementById('total-cost');
+  const elAvgCost = document.getElementById('avg-cost');
+  
+  const elRpmValue = document.getElementById('rpm-value');
+  const elTotalRequests = document.getElementById('total-requests');
+  
+  const tokensGauge = document.getElementById('tokens-gauge');
+  const costGauge = document.getElementById('cost-gauge');
+  const rpmGauge = document.getElementById('rpm-gauge');
+  const tbody = document.getElementById('telemetry-tbody');
+
+  // Track timestamps for RPM calculation
+  const requestTimestamps = [];
+
+  function calculateCost(model, inTokens, outTokens) {
+    const rates = PRICING[model] || PRICING['default'];
+    return (inTokens / 1000000) * rates.in + (outTokens / 1000000) * rates.out;
+  }
+
+  function formatNumber(num) {
+    return new Intl.NumberFormat('en-US').format(num);
+  }
+
+  function updateGauges() {
+    // Max tokens scale (e.g., 50k max for the gauge visual to be more reactive to test data)
+    const MAX_TOKENS = 50000;
+    let tokenPct = Math.min(totalTokens / MAX_TOKENS, 1);
+    tokensGauge.style.strokeDashoffset = 283 - (283 * tokenPct);
+
+    // Max cost scale (e.g. $0.5 max for reactivity)
+    const MAX_COST = 0.5;
+    let costPct = Math.min(totalCost / MAX_COST, 1);
+    costGauge.style.strokeDashoffset = 283 - (283 * costPct);
+
+    // RPM gauge (max 60 RPM)
+    const now = Date.now();
+    // Keep requests from last 60 seconds
+    while (requestTimestamps.length > 0 && now - requestTimestamps[0] > 60000) {
+      requestTimestamps.shift();
+    }
+    const rpm = requestTimestamps.length;
+    let rpmPct = Math.min(rpm / 60, 1);
+    rpmGauge.style.strokeDashoffset = 283 - (283 * rpmPct);
+    
+    elRpmValue.textContent = rpm;
+  }
+
+  // Periodic RPM update
+  setInterval(updateGauges, 2000);
+
+  function renderRow(tel, isNew = false) {
+    const cost = calculateCost(tel.model, tel.inputTokens, tel.outputTokens);
+    
+    // Update State
+    totalTokens += (tel.inputTokens + tel.outputTokens);
+    totalInputTokens += tel.inputTokens;
+    totalOutputTokens += tel.outputTokens;
+    totalCost += cost;
+    totalRequests += 1;
+    requestTimestamps.push(new Date(tel.timestamp).getTime());
+
+    // Update DOM Text
+    elTotalTokens.textContent = formatNumber(totalTokens);
+    elInputTokens.textContent = formatNumber(totalInputTokens);
+    elOutputTokens.textContent = formatNumber(totalOutputTokens);
+    
+    elTotalCost.textContent = `$${totalCost.toFixed(3)}`;
+    elAvgCost.textContent = `$${(totalCost / totalRequests).toFixed(4)}`;
+    elTotalRequests.textContent = formatNumber(totalRequests);
+
+    // Create Row
+    const tr = document.createElement('tr');
+    if (isNew) tr.className = 'new-row';
+    
+    const time = new Date(tel.timestamp).toLocaleTimeString();
+    
+    tr.innerHTML = `
+      <td>${time}</td>
+      <td><strong>${tel.provider.toUpperCase()}</strong><br><span style="color:#94a3b8;font-size:0.75rem">${tel.model}</span></td>
+      <td>${tel.projectId}</td>
+      <td>${tel.userId}</td>
+      <td class="text-right">${formatNumber(tel.inputTokens)}</td>
+      <td class="text-right">${formatNumber(tel.outputTokens)}</td>
+      <td class="text-right" style="color:var(--neon-cyan)">$${cost.toFixed(4)}</td>
+    `;
+    
+    tbody.insertBefore(tr, tbody.firstChild);
+
+    // Keep table from growing infinitely
+    if (tbody.children.length > 50) {
+      tbody.removeChild(tbody.lastChild);
+    }
+
+    updateGauges();
+  }
+
+  let dashboardInitialized = false;
+  let evtSource = null;
+
+  function initializeDashboard() {
+    if (dashboardInitialized) return;
+    dashboardInitialized = true;
+
+    // 1. Fetch initial history
+    tbody.innerHTML = ''; // Clear rows
+    fetch('/api/telemetry')
+      .then(res => res.json())
+      .then(data => {
+        // Clear states before reloading
+        totalTokens = 0;
+        totalInputTokens = 0;
+        totalOutputTokens = 0;
+        totalCost = 0.0;
+        totalRequests = 0;
+        requestTimestamps.length = 0;
+
+        data.reverse().forEach(tel => renderRow(tel, false));
+      })
+      .catch(err => console.error("Error fetching telemetry:", err));
+
+    // 2. Connect to live SSE stream
+    if (evtSource) {
+      evtSource.close();
+    }
+    evtSource = new EventSource('/api/telemetry/stream');
+    evtSource.onmessage = (e) => {
+      try {
+        const tel = JSON.parse(e.data);
+        renderRow(tel, true);
+      } catch (err) {
+        console.error("Stream parse error:", err);
+      }
+    };
+  }
+
+  // ==========================================
+  // Configuration & Security Lock Logic
+  // ==========================================
+  const configForm = document.getElementById('config-form');
+  const openaiPreset = document.getElementById('openaiPreset');
+  const openaiApiUrl = document.getElementById('openaiApiUrl');
+  const configStatus = document.getElementById('config-status');
+
+  const gaugeWrapper = document.getElementById('gauge-cluster-wrapper');
+  const dataWrapper = document.getElementById('data-panel-wrapper');
+
+  function getGatewayKey() {
+    return localStorage.getItem('gatewayKey') || '';
+  }
+
+  function setLockedState(isLocked) {
+    if (isLocked) {
+      gaugeWrapper.classList.add('locked-section');
+      dataWrapper.classList.add('locked-section');
+    } else {
+      gaugeWrapper.classList.remove('locked-section');
+      dataWrapper.classList.remove('locked-section');
+    }
+  }
+
+  function showOnboardingModal() {
+    const modal = document.getElementById('onboarding-modal');
+    if (modal) modal.classList.remove('hidden');
+  }
+
+  function checkAuthAndLoad() {
+    const key = getGatewayKey();
+    if (!key) {
+      setLockedState(true);
+      showOnboardingModal();
+      return;
+    }
+
+    // Validate key and fetch configs
+    fetch('/api/config', {
+      headers: { 'x-gateway-key': key }
+    })
+      .then(res => {
+        if (res.status === 401) {
+          localStorage.removeItem('gatewayKey');
+          setLockedState(true);
+          showOnboardingModal();
+          alert("Unauthorized. Incorrect Gateway Secret Key.");
+          throw new Error("Unauthorized. Incorrect Gateway Secret Key.");
+        }
+        return res.json();
+      })
+      .then(config => {
+        // Success: Unlock dashboard!
+        setLockedState(false);
+        initializeDashboard();
+
+        document.getElementById('agencyGatewayKey').value = config.agencyGatewayKey || '';
+        document.getElementById('openaiApiUrl').value = config.openaiApiUrl || '';
+        document.getElementById('openaiApiKey').placeholder = config.openaiApiKey || 'Enter API key (leave blank to keep current)';
+        document.getElementById('anthropicApiUrl').value = config.anthropicApiUrl || '';
+        document.getElementById('anthropicApiKey').placeholder = config.anthropicApiKey || 'Enter API key (leave blank to keep current)';
+        
+        // Select preset if matched
+        let foundPreset = false;
+        for (const option of openaiPreset.options) {
+          if (option.value === config.openaiApiUrl) {
+            openaiPreset.value = config.openaiApiUrl;
+            foundPreset = true;
+            break;
+          }
+        }
+        if (!foundPreset && config.openaiApiUrl) {
+          openaiPreset.value = 'custom';
+        }
+      })
+      .catch(err => {
+        console.error("Config load error:", err);
+      });
+  }
+
+  // Run initial check
+  checkAuthAndLoad();
+
+  // Handle preset selection
+  openaiPreset.addEventListener('change', (e) => {
+    if (e.target.value !== 'custom') {
+      openaiApiUrl.value = e.target.value;
+    }
+  });
+
+  // Handle save and unlock
+  configForm.addEventListener('submit', (e) => {
+    e.preventDefault();
+    
+    configStatus.textContent = "Saving and validating...";
+    configStatus.className = "config-status";
+
+    const enteredKey = document.getElementById('agencyGatewayKey').value;
+    localStorage.setItem('gatewayKey', enteredKey);
+
+    const payload = {
+      agencyGatewayKey: enteredKey,
+      openaiApiUrl: document.getElementById('openaiApiUrl').value,
+      anthropicApiUrl: document.getElementById('anthropicApiUrl').value,
+    };
+
+    const openaiApiKey = document.getElementById('openaiApiKey').value;
+    if (openaiApiKey) payload.openaiApiKey = openaiApiKey;
+
+    const anthropicApiKey = document.getElementById('anthropicApiKey').value;
+    if (anthropicApiKey) payload.anthropicApiKey = anthropicApiKey;
+
+    fetch('/api/config', {
+      method: 'POST',
+      headers: { 
+        'Content-Type': 'application/json',
+        'x-gateway-key': enteredKey
+      },
+      body: JSON.stringify(payload)
+    })
+    .then(res => {
+      if (res.status === 401) {
+        localStorage.removeItem('gatewayKey');
+        setLockedState(true);
+        throw new Error("Invalid Gateway Secret Key. Access Denied.");
+      }
+      return res.json();
+    })
+    .then(data => {
+      if (data.status === 'success') {
+        configStatus.textContent = "Dashboard unlocked and configurations saved!";
+        configStatus.classList.add('success');
+        
+        setLockedState(false);
+        initializeDashboard();
+
+        // Clear password fields so placeholders remain
+        document.getElementById('openaiApiKey').value = '';
+        document.getElementById('anthropicApiKey').value = '';
+      } else {
+        configStatus.textContent = data.error || "Failed to save.";
+        configStatus.classList.add('error');
+      }
+      setTimeout(() => configStatus.textContent = "", 4000);
+    })
+    .catch(err => {
+      configStatus.textContent = err.message || "Network error. Failed to save.";
+      configStatus.classList.add('error');
+      setTimeout(() => configStatus.textContent = "", 4000);
+    });
+  });
+
+  // ==========================================
+  // Tab Switching Logic
+  // ==========================================
+  const tabButtons = document.querySelectorAll('.tab-btn');
+  const tabContents = document.querySelectorAll('.tab-content');
+
+  tabButtons.forEach(btn => {
+    btn.addEventListener('click', () => {
+      const targetTab = btn.getAttribute('data-tab');
+
+      tabButtons.forEach(b => b.classList.remove('active'));
+      tabContents.forEach(c => c.classList.remove('active'));
+
+      btn.classList.add('active');
+      const targetElement = document.getElementById(`tab-${targetTab}`);
+      if (targetElement) {
+        targetElement.classList.add('active');
+      }
+    });
+  });
+
+  // ==========================================
+  // Onboarding Modal Logic
+  // ==========================================
+  const modal = document.getElementById('onboarding-modal');
+  const btnNext = document.getElementById('btn-next');
+  const btnPrev = document.getElementById('btn-prev');
+  const btnFinish = document.getElementById('btn-finish');
+  const steps = document.querySelectorAll('.wizard-step');
+  const dots = document.querySelectorAll('.step-dot');
+  
+  let currentStep = 1;
+  const totalSteps = steps.length;
+
+  function updateModalUI() {
+    steps.forEach(step => {
+      step.classList.remove('active', 'exit-left');
+      const stepNum = parseInt(step.id.split('-')[1]);
+      if (stepNum < currentStep) {
+        step.classList.add('exit-left');
+      } else if (stepNum === currentStep) {
+        step.classList.add('active');
+      }
+    });
+
+    dots.forEach(dot => {
+      const dotStep = parseInt(dot.getAttribute('data-step'));
+      dot.classList.toggle('active', dotStep === currentStep);
+    });
+
+    if (btnPrev) btnPrev.style.visibility = currentStep === 1 ? 'hidden' : 'visible';
+    
+    if (currentStep === totalSteps) {
+      if (btnNext) btnNext.classList.add('hidden');
+      if (btnFinish) btnFinish.classList.remove('hidden');
+      
+      const enteredKey = document.getElementById('onboardingGatewayKey').value;
+      const previewKeyEl = document.getElementById('preview-key');
+      if (previewKeyEl) {
+        previewKeyEl.textContent = enteredKey || 'your-key';
+      }
+    } else {
+      if (btnNext) btnNext.classList.remove('hidden');
+      if (btnFinish) btnFinish.classList.add('hidden');
+    }
+  }
+
+  if (btnNext) {
+    btnNext.addEventListener('click', () => {
+      if (currentStep < totalSteps) {
+        currentStep++;
+        updateModalUI();
+      }
+    });
+  }
+
+  if (btnPrev) {
+    btnPrev.addEventListener('click', () => {
+      if (currentStep > 1) {
+        currentStep--;
+        updateModalUI();
+      }
+    });
+  }
+
+  if (btnFinish) {
+    btnFinish.addEventListener('click', () => {
+      const enteredKey = document.getElementById('onboardingGatewayKey').value;
+      if (!enteredKey) {
+        alert("Please enter your Gateway Secret Key to continue.");
+        currentStep = 2;
+        updateModalUI();
+        return;
+      }
+      
+      localStorage.setItem('gatewayKey', enteredKey);
+      if (modal) modal.classList.add('hidden');
+      checkAuthAndLoad();
+    });
+  }
+});
+
+// ==========================================
+// Copy Code Snippet Helper
+// ==========================================
+window.copySnippet = function(id, btn) {
+  const codeElement = document.getElementById(id);
+  if (!codeElement) return;
+  const code = codeElement.textContent;
+  navigator.clipboard.writeText(code).then(() => {
+    const originalText = btn.textContent;
+    btn.textContent = "Copied!";
+    btn.style.borderColor = "var(--accent-green)";
+    btn.style.color = "var(--accent-green)";
+    setTimeout(() => {
+      btn.textContent = originalText;
+      btn.style.borderColor = "";
+      btn.style.color = "";
+    }, 2000);
+  }).catch(err => {
+    console.error("Failed to copy code snippet:", err);
+  });
+};
+