gebeya-whatsapp-otp/README.md

React WhatsApp OTP verification component with Supabase integration

# Gebeya WhatsApp OTP

A React component library for WhatsApp OTP verification with Supabase integration. This package provides a complete solution for implementing phone number verification using WhatsApp OTP in your React applications.

## Features

- ✅ **WhatsApp OTP Integration** - Send and verify OTP codes via WhatsApp
- ✅ **Supabase Backend** - Built-in Supabase integration for data storage
- ✅ **React Components** - Ready-to-use UI components
- ✅ **TypeScript Support** - Full TypeScript support with type definitions
- ✅ **Customizable Styling** - Tailwind CSS support with custom styling options
- ✅ **Country Selection** - Multi-country support with country code selection
- ✅ **Error Handling** - Comprehensive error handling and user feedback
- ✅ **Security Features** - Rate limiting, attempt tracking, and phone suspension
- ✅ **Accessibility** - WCAG compliant components

## Quick Start

### Installation

```bash
npm install gebeya-whatsapp-otp
```

### Basic Usage

```tsx
import React from "react";
import {
  WhatsAppOTPProvider,
  VerifyWithWhatsAppButton,
  WhatsAppOTPModal,
} from "gebeya-whatsapp-otp";

function App() {
  const config = {
    supabaseUrl: "YOUR_SUPABASE_URL",
    supabaseKey: "YOUR_SUPABASE_ANON_KEY",
  };

  return (
    <WhatsAppOTPProvider config={config}>
      <div>
        <h1>Welcome</h1>
        <VerifyWithWhatsAppButton>
          Verify with WhatsApp
        </VerifyWithWhatsAppButton>
      </div>
      <WhatsAppOTPModal />
    </WhatsAppOTPProvider>
  );
}
```

## Documentation

📖 **[Complete Setup Guide](SETUP_GUIDE.md)** - Detailed installation and configuration instructions

## Components

### `WhatsAppOTPProvider`

Context provider that manages the OTP verification state and Supabase connection.

### `VerifyWithWhatsAppButton`

Button component that triggers the OTP verification flow. Supports multiple variants and sizes.

### `WhatsAppOTPModal`

Modal component that handles the phone number input and OTP verification interface.

### `useWhatsAppOTP`

Custom hook for advanced usage and custom implementations.

## Examples

### Basic Implementation

```tsx
import {
  WhatsAppOTPProvider,
  VerifyWithWhatsAppButton,
  WhatsAppOTPModal,
} from "gebeya-whatsapp-otp";

function LoginPage() {
  const config = {
    supabaseUrl: process.env.REACT_APP_SUPABASE_URL!,
    supabaseKey: process.env.REACT_APP_SUPABASE_ANON_KEY!,
  };

  const callbacks = {
    onSuccess: (phoneNumber: string) => {
      console.log("Phone verified:", phoneNumber);
      // Redirect to dashboard
    },
    onError: (error: string) => {
      console.error("Verification failed:", error);
      // Show error message
    },
  };

  return (
    <WhatsAppOTPProvider config={config} callbacks={callbacks}>
      <div className="min-h-screen flex items-center justify-center">
        <div className="text-center">
          <h1 className="text-2xl font-bold mb-4">Welcome</h1>
          <p className="text-gray-600 mb-6">Please verify your phone number</p>
          <VerifyWithWhatsAppButton className="w-full">
            Verify Phone Number
          </VerifyWithWhatsAppButton>
        </div>
      </div>
      <WhatsAppOTPModal />
    </WhatsAppOTPProvider>
  );
}
```

### Custom Styling

```tsx
<VerifyWithWhatsAppButton
  variant="outline"
  size="lg"
  className="bg-green-600 hover:bg-green-700 text-white"
>
  Custom Styled Button
</VerifyWithWhatsAppButton>
```

### Custom Countries

```tsx
const customCountries = [
  { code: "+1", country: "United States", flag: "🇺🇸" },
  { code: "+44", country: "United Kingdom", flag: "🇬🇧" },
  { code: "+251", country: "Ethiopia", flag: "🇪🇹" },
];

<WhatsAppOTPModal countries={customCountries} />;
```

## Requirements

- React 16.8.0 or higher
- React-DOM 16.8.0 or higher
- Supabase account and project
- Node.js 14.0 or higher

## Browser Support

- Chrome 60+
- Firefox 55+
- Safari 12+
- Edge 79+

## Contributing

We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.

## License

MIT License - see the [LICENSE](LICENSE) file for details.

## Support

- 📖 [Documentation](SETUP_GUIDE.md)
- 🐛 [Report Issues](https://github.com/gebeyainc/gebeya-whatsapp-otp/issues)
- 💬 [Discussions](https://github.com/gebeyainc/gebeya-whatsapp-otp/discussions)

## Changelog

See [CHANGELOG.md](CHANGELOG.md) for a list of changes and version history.