npm package: @ideodyne/validation-engine
Description: Modular validation infrastructure for SaaS products - Next.js + pnpm compatible
Author: Ideodyne
Latest version: 1.2.5

# @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):

```bash
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:

```bash
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:

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

### Peer Dependencies

Make sure you have these installed:

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

Optional peer dependencies (install as needed):

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

## 🎯 Quick Start

### 1. Create Configuration

```typescript
// 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: 'hello@myproduct.com',
    },
    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`:

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

### 3. Wrap Your App

```typescript
// 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

```typescript
// 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)

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

export const POST = waitlistJoinHandler;
```

### 6. Add Dashboard (Optional - requires recharts)

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

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

## 📚 Documentation

- [Installation Guide](docs/installation.md)
- [Configuration](docs/configuration.md)
- [Payment Setup](docs/payment-setup.md)
- [API Reference](docs/api-reference.md)

## 🏗️ 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](docs/configuration.md) 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

```bash
# 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)

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

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

### API Routes

```typescript
// 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)

```typescript
// 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.**