tamil-captcha/README.md

A lightweight math-based CAPTCHA generator in Tamil language for Node.js and browser applications

# 🧪 tamil-captcha

A minimal and lightweight math CAPTCHA generator in the **Tamil language** 🇮🇳 — useful for websites, forms, or apps that serve Tamil-speaking users.

✅ Tamil numerals & operations ✅ Easy to use in Node.js/Express or frontend ✅ No dependencies

## Installation

```bash
npm install tamil-captcha
```

## Quick Start

```javascript
const { generateCaptcha, verifyCaptcha } = require('tamil-captcha');

// Generate a CAPTCHA
const captcha = generateCaptcha();
console.log(captcha.question); // "ஐந்து + இரண்டு = ?"
console.log(captcha.answer);   // 7

// Verify user input
console.log(verifyCaptcha("7", captcha.answer)); // true
console.log(verifyCaptcha("5", captcha.answer)); // false
```

## API Reference

### generateCaptcha(options?)

Generates a Tamil math CAPTCHA challenge.

**Parameters:**
- `options` (Object, optional):
  - `minNumber` (number): Minimum number to use (1-10, default: 1)
  - `maxNumber` (number): Maximum number to use (1-10, default: 10)
  - `operations` (string[]): Operations to use (default: ['+', '-', '*'])

**Returns:**
```javascript
{
  question: string,    // Tamil question like "மூன்று × இரண்டு = ?"
  answer: number,      // Correct numeric answer
  operation: string,   // Operation used ('+', '-', or '*')
  numbers: number[],   // The two numbers used
  metadata: {
    tamilNumbers: string[],  // Tamil words for the numbers
    operationWord: string    // Tamil word for operation
  }
}
```

### verifyCaptcha(userInput, actualAnswer)

Verifies if the user's input matches the correct answer.

**Parameters:**
- `userInput` (string | number): User's answer
- `actualAnswer` (number): Correct answer from generateCaptcha()

**Returns:** `boolean` - True if the answer is correct

### Helper Functions

#### getTamilNumber(number)
```javascript
getTamilNumber(5); // "ஐந்து"
```

#### getAllTamilNumbers()
```javascript
getAllTamilNumbers(); 
// { 1: 'ஒன்று', 2: 'இரண்டு', 3: 'மூன்று', ... }
```

#### getOperations()
```javascript
getOperations();
// [
//   { key: '+', symbol: '+', word: 'கூட்டல்' },
//   { key: '-', symbol: '-', word: 'கழித்தல்' },
//   { key: '*', symbol: '×', word: 'பெருக்கல்' }
// ]
```

## Usage Examples

### Basic Express.js Integration

```javascript
const express = require('express');
const { generateCaptcha, verifyCaptcha } = require('tamil-captcha');

const app = express();
app.use(express.json());

// Store active CAPTCHAs (use Redis/database in production)
const activeCaptchas = new Map();

app.get('/captcha', (req, res) => {
  const captcha = generateCaptcha();
  const sessionId = Date.now().toString();
  
  activeCaptchas.set(sessionId, captcha.answer);
  
  res.json({
    sessionId,
    question: captcha.question
  });
});

app.post('/verify-captcha', (req, res) => {
  const { sessionId, answer } = req.body;
  const correctAnswer = activeCaptchas.get(sessionId);
  
  if (!correctAnswer) {
    return res.status(400).json({ error: 'Invalid session' });
  }
  
  const isValid = verifyCaptcha(answer, correctAnswer);
  activeCaptchas.delete(sessionId); // Clean up
  
  res.json({ valid: isValid });
});

app.listen(3000);
```

### React Component Example

```jsx
import React, { useState, useEffect } from 'react';

function TamilCaptcha({ onVerify }) {
  const [captcha, setCaptcha] = useState(null);
  const [userInput, setUserInput] = useState('');

  const generateNewCaptcha = () => {
    // Import the package in your React app
    const { generateCaptcha } = require('tamil-captcha');
    setCaptcha(generateCaptcha());
    setUserInput('');
  };

  useEffect(() => {
    generateNewCaptcha();
  }, []);

  const handleSubmit = () => {
    if (captcha) {
      const { verifyCaptcha } = require('tamil-captcha');
      const isCorrect = verifyCaptcha(userInput, captcha.answer);
      onVerify(isCorrect);
      
      if (!isCorrect) {
        generateNewCaptcha(); // Generate new CAPTCHA on wrong answer
      }
    }
  };

  return (
    <div className="tamil-captcha">
      <div className="captcha-question">
        {captcha ? captcha.question : 'Loading...'}
      </div>
      <input
        type="number"
        value={userInput}
        onChange={(e) => setUserInput(e.target.value)}
        placeholder="உங்கள் பதில்..."
      />
      <button onClick={handleSubmit}>சரிபார்க்க</button>
      <button onClick={generateNewCaptcha}>புதிய கேள்வி</button>
    </div>
  );
}
```

### Custom Configuration

```javascript
const { generateCaptcha } = require('tamil-captcha');

// Only addition and subtraction, numbers 1-5
const captcha1 = generateCaptcha({
  minNumber: 1,
  maxNumber: 5,
  operations: ['+', '-']
});

// Only multiplication, small numbers
const captcha2 = generateCaptcha({
  minNumber: 1,
  maxNumber: 3,
  operations: ['*']
});

console.log(captcha1.question); // "நான்கு - ஒன்று = ?"
console.log(captcha2.question); // "இரண்டு × மூன்று = ?"
```

## Tamil Language Support

The package supports Tamil numerals from 1 to 10:

| Number | Tamil |
|--------|-------|
| 1 | ஒன்று |
| 2 | இரண்டு |
| 3 | மூன்று |
| 4 | நான்கு |
| 5 | ஐந்து |
| 6 | ஆறு |
| 7 | ஏழு |
| 8 | எட்டு |
| 9 | ஒன்பது |
| 10 | பத்து |

**Operations:**
- கூட்டல் (Addition): `+`
- கழித்தல் (Subtraction): `-`
- பெருக்கல் (Multiplication): `×`

## Browser Support

This package works in both Node.js and browser environments. For browser usage, you can use a bundler like Webpack, Rollup, or Browserify.

## Security Notes

- Always validate CAPTCHA answers on the server side
- Use session management to prevent replay attacks
- Consider implementing rate limiting
- Store CAPTCHA answers securely (preferably in Redis or encrypted storage)
- Generate new CAPTCHAs after failed attempts

## Contributing

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## License

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

## Changelog

### v1.0.0
- Initial release
- Basic math operations in Tamil
- Support for numbers 1-10
- Node.js and browser compatibility
- Zero dependencies

---

Made with ❤️ for the Tamil-speaking community