@ideodyne/validation-engine

Version 1.1.0 - Modular Validation Infrastructure for SaaS Products

A modular validation infrastructure package that enables rapid idea validation and product launch. Core features are lightweight with no heavy dependencies. Dashboard components are optional and can be added when needed.

🚀 Features

Base Features (v1.0.0)

• ✅ Waitlist management with referral system
• ✅ Beta invite system
• ✅ NPS surveys
• ✅ A/B experiments
• ✅ Email sequences
• ✅ Analytics dashboard

Enhanced Features (v1.1.0)

• ✅ Anonymous visitor tracking
• ✅ Beta screening questions with auto-scoring

Tier 1 CRITICAL Features (v2.0.0) 🔥

• ✅ Payment collection (pre-orders) - Stripe integration for deposits
• ✅ Exit intent surveys - Understand why people don't convert
• ✅ Engagement scoring - Predict who will actually use your product

Tier 2 HIGH VALUE Features (v2.0.0) ⭐

• ✅ User interview system - Schedule and conduct customer interviews
• ✅ Pricing sensitivity testing - A/B test price points and willingness-to-pay
• ✅ Behavioral tracking - Return visitor patterns and engagement trends

Total: 8+ powerful validation features in one package

📦 Installation

For pnpm users (recommended):

pnpm add @ideodyne/validation-engine

Important: If using pnpm, add this to your project's .npmrc:

public-hoist-pattern[]=*react*
public-hoist-pattern[]=*react-dom*

This prevents React duplication issues.

For npm/yarn users:

npm install @ideodyne/validation-engine

# or

yarn add @ideodyne/validation-engine

Core Features (Lightweight)

Core features work out of the box with minimal dependencies - no recharts, no heavy UI libraries.

With Dashboard (Optional)

If you want to use the metrics dashboard UI, install recharts:

pnpm add @ideodyne/validation-engine recharts
# or
npm install @ideodyne/validation-engine recharts

Peer Dependencies

Make sure you have these installed:

pnpm add react react-dom next @prisma/client
# or
npm install react react-dom next @prisma/client

Optional peer dependencies (install as needed):

pnpm add resend posthog-js recharts stripe @stripe/stripe-js

🎯 Quick Start

1. Create Configuration

// validation.config.ts
import { defineConfig } from '@ideodyne/validation-engine';

export default defineConfig({
  product: {
    name: 'My Product',
    tagline: 'The best product ever',
    description: 'A description of your product',
    domain: 'myproduct.com',
  },
  
  customer: {
    persona: 'Your target customer',
    painPoint: 'The problem you solve',
    desiredOutcome: 'The outcome they want',
  },
  
  metrics: {
    northStar: 'key_metric',
    activationEvent: 'first_action',
    keyActions: ['action1', 'action2'],
  },
  
  targets: {
    waitlistSignups: 200,
    signupRatePerDay: 5,
    betaUsers: 50,
    activationRate: 0.85,
    npsScore: 40,
    retention30d: 0.60,
  },
  
  integrations: {
    email: {
      provider: 'resend',
      apiKey: process.env.RESEND_API_KEY!,
      from: '[email protected]',
    },
    analytics: {
      provider: 'posthog',
      apiKey: process.env.NEXT_PUBLIC_POSTHOG_KEY!,
      host: process.env.NEXT_PUBLIC_POSTHOG_HOST,
    },
  },
  
  features: {
    waitlist: true,
    betaInvites: true,
    nps: true,
    experiments: true,
    sessionRecording: false,
    visitorTracking: true,
    betaScreening: true,
    preOrders: true,
    exitSurveys: true,
    engagementScoring: true,
    userInterviews: true,
    pricingSensitivity: true,
    behavioralTracking: true,
  },
  
  branding: {
    colors: {
      primary: '#3B82F6',
      secondary: '#8B5CF6',
      accent: '#10B981',
    },
    font: {
      heading: 'Inter',
      body: 'Inter',
    },
  },
});

2. Add Prisma Models

Copy the validation engine Prisma schema into your schema.prisma:

// See full schema in src/prisma/schema.prisma
model WaitlistUser { ... }
model VisitorSession { ... }
model EngagementScore { ... }

3. Wrap Your App

// app/layout.tsx
import { ValidationEngineProvider } from '@ideodyne/validation-engine';
import validationConfig from '@/validation.config';

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <ValidationEngineProvider config={validationConfig}>
          {children}
        </ValidationEngineProvider>
      </body>
    </html>
  );
}

4. Add Tracking to Landing Page

// Core tracking - works without recharts
import { 
  VisitorTracker, 
  EngagementTracker,
  WaitlistForm 
} from '@ideodyne/validation-engine';

export default function Home() {
  return (
    <>
      <VisitorTracker />
      <EngagementTracker />
      <WaitlistForm />
      {/* Your content */}
    </>
  );
}

5. Add API Handlers (Optional)

// app/api/waitlist/join/route.ts
import { waitlistJoinHandler } from '@ideodyne/validation-engine/api';

export const POST = waitlistJoinHandler;

6. Add Dashboard (Optional - requires recharts)

// Only import dashboard if you installed recharts
import { ValidationDashboard } from '@ideodyne/validation-engine/dashboard';

export default function AdminPage() {
  return <ValidationDashboard />;
}

📚 Documentation

• Installation Guide
• Configuration
• Payment Setup
• API Reference

🏗️ Project Structure

@ideodyne/validation-engine/
├── src/
│   ├── core/          # Core features (lightweight)
│   │   ├── components/ # Tracking, waitlist, UI components
│   │   ├── hooks/      # React hooks
│   │   └── api/        # Core API handlers
│   ├── dashboard/      # Dashboard (optional, requires recharts)
│   │   └── components/ # Metrics UI, charts
│   ├── api/           # API handlers export
│   ├── lib/           # Core business logic
│   ├── types/         # TypeScript types
│   ├── config/        # Configuration system
│   └── prisma/        # Database schema

📦 Module Structure

The package exports three modules:

Core (@ideodyne/validation-engine)

• ✅ Tracking components (VisitorTracker, EngagementTracker)
• ✅ Waitlist form
• ✅ Exit intent modal
• ✅ UI components (Button, Input, Modal, etc.)
• ✅ Hooks (useValidation, useEngagement, etc.)
• ✅ API handlers
• ✅ No heavy dependencies

Dashboard (@ideodyne/validation-engine/dashboard)

• 📊 ValidationDashboard
• 📊 MetricsDashboard
• 📊 Charts and visualizations
• ⚠️ Requires recharts (install separately)

API (@ideodyne/validation-engine/api)

• 🔌 Route handlers for Next.js
• 🔌 waitlistJoinHandler
• 🔌 visitorTrackHandler
• 🔌 engagementUpdateHandler
• 🔌 exitSurveySubmitHandler

🔧 Configuration

See Configuration Documentation for complete configuration options.

🎨 Components

Core Components (Default Export)

• <VisitorTracker /> - Anonymous visitor tracking
• <EngagementTracker /> - Engagement scoring tracker
• <WaitlistForm /> - Email capture form
• <ExitIntentModal /> - Exit intent survey modal
• <ValidationEngineProvider /> - Main provider component
• UI Components: <Button />, <Input />, <Modal />, <Alert />, etc.

Dashboard Components (/dashboard - requires recharts)

• <ValidationDashboard /> - Main validation overview
• <MetricsDashboard /> - Metrics overview widget
• <ValidationScore /> - Score visualization
• <ExitSurveyInsights /> - Exit survey analytics with charts
• <StageProgress /> - Validation stage progress
• <ValidationStatus /> - Validation status display

📊 Features in Detail

Payment Collection (Pre-orders)

Collect refundable deposits to validate true intent. Stripe integration with webhooks.

Exit Intent Surveys

Capture feedback from users who leave without signing up. Understand objections.

Engagement Scoring

Score visitors based on behavior (time on site, pages viewed, scroll depth, etc.).

User Interviews

Schedule and conduct customer interviews with Calendly/Cal.com integration.

Pricing Sensitivity Testing

A/B test different price points and collect willingness-to-pay data.

Behavioral Tracking

Track user journey patterns and identify conversion paths.

🚦 Development

# Install dependencies
npm install

# Generate Prisma client
npx prisma generate

# Run migrations
npx prisma migrate dev

# Build package
npm run build

# Run tests
npm test

💡 Usage Examples

Core Tracking (No Dashboard)

import { 
  ValidationEngineProvider,
  VisitorTracker,
  EngagementTracker,
  WaitlistForm 
} from '@ideodyne/validation-engine';

export default function Home() {
  return (
    <>
      <VisitorTracker />
      <EngagementTracker />
      <WaitlistForm />
    </>
  );
}

API Routes

// app/api/waitlist/join/route.ts
import { waitlistJoinHandler } from '@ideodyne/validation-engine/api';
export const POST = waitlistJoinHandler;

// app/api/visitor/track/route.ts
import { visitorTrackHandler } from '@ideodyne/validation-engine/api';
export const POST = visitorTrackHandler;

Dashboard (Optional)

// Install recharts first: npm install recharts
import { ValidationDashboard } from '@ideodyne/validation-engine/dashboard';

export default function AdminPage() {
  return <ValidationDashboard />;
}

✅ Benefits

• 🎯 Use core features without heavy dependencies
• 📊 Add dashboard only when needed
• 🚀 Faster builds and smaller bundles
• 🔧 Modular and flexible
• ⚡ No dependency conflicts

📝 License

MIT

👥 Author

Ideodyne

Built for rapid SaaS validation. Validate every idea. Build once. Use forever.