@businessflow/leads/README.md

Generic lead collection and form submission utilities with server-side API route handlers

# @businessflow/leads

Generic lead collection and form submission utilities for React and NextJS applications.

## Features

- 🚀 **Framework Agnostic**: Works with React, NextJS, and vanilla JavaScript
- 🔒 **Secure**: Server-side API key handling, reCAPTCHA integration
- 📱 **Responsive**: Mobile-friendly form components
- 🎨 **Customizable**: Flexible styling and field configuration
- 📝 **TypeScript**: Full type safety and IntelliSense support
- ⚡ **Modern**: Built with latest React patterns and NextJS features

## Installation

```bash
npm install @businessflow/leads
```

## Quick Start

### 1. Create API Route (NextJS App Router)

```typescript
// app/api/lead/route.ts
import { createLeadHandler } from '@businessflow/leads/server';

export const POST = createLeadHandler({
  onSubmit: async (data) => {
    // Your business logic here - submit to your API
    const response = await fetch('https://your-api.com/leads', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${process.env.YOUR_API_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(data)
    });
    
    return {
      success: response.ok,
      message: response.ok ? 'Lead submitted successfully' : 'Submission failed',
      id: response.ok ? await response.json().then(r => r.id) : undefined
    };
  },
  recaptcha: {
    secretKey: process.env.RECAPTCHA_SECRET_KEY!
  }
});
```

### 2. Use in Your Components

#### Pre-built Component
```typescript
import { ContactForm } from '@businessflow/leads/react';

export default function ContactPage() {
  return (
    <ContactForm
      recaptcha={{ siteKey: process.env.NEXT_PUBLIC_RECAPTCHA_SITE_KEY! }}
      onSuccess={(response) => console.log('Success!', response)}
      onError={(error) => console.error('Error:', error)}
    />
  );
}
```

#### Custom Hook for Custom Forms
```typescript
import { useContactForm } from '@businessflow/leads/react';

export default function CustomContactForm() {
  const {
    formData,
    errors,
    state,
    handleChange,
    handleSubmit,
    handleRetry,
    resetForm
  } = useContactForm({
    endpoint: '/api/lead',
    recaptcha: { 
      siteKey: process.env.NEXT_PUBLIC_RECAPTCHA_SITE_KEY!,
      action: 'contact_form'
    },
    onSuccess: (response) => console.log('Success!', response),
    onError: (error) => console.error('Error:', error),
    maxRetries: 3
  });

  return (
    <form onSubmit={(e) => { e.preventDefault(); handleSubmit(); }}>
      <input
        type="text"
        placeholder="First Name"
        value={formData.firstName}
        onChange={(e) => handleChange('firstName', e.target.value)}
      />
      {errors.firstName && <span>{errors.firstName}</span>}
      
      <input
        type="text"
        placeholder="Last Name"
        value={formData.lastName}
        onChange={(e) => handleChange('lastName', e.target.value)}
      />
      {errors.lastName && <span>{errors.lastName}</span>}
      
      <input
        type="email"
        placeholder="Email"
        value={formData.email}
        onChange={(e) => handleChange('email', e.target.value)}
      />
      {errors.email && <span>{errors.email}</span>}
      
      <button type="submit" disabled={state.isSubmitting}>
        {state.isSubmitting ? 'Submitting...' : 'Submit'}
      </button>
      
      {state.error && state.canRetry && (
        <button onClick={handleRetry} disabled={state.isSubmitting}>
          Retry ({state.retryCount}/{3})
        </button>
      )}
      
      {state.isSuccess && <div>Form submitted successfully!</div>}
      {state.error && <div>Error: {state.error}</div>}
    </form>
  );
}
```

## Documentation

- [API Reference](./docs/api.md)
- [Examples](./examples/)
- [Migration Guide](./docs/migration.md)

## License

MIT