npm package: @nostrbox/otp-zen
Description: A simple and flexible OTP (One-Time Password) generator with TypeScript support
Latest version: 1.1.0

# OTP Zen

A simple and flexible OTP (One-Time Password) generator with TypeScript support. Generate secure numeric and alphanumeric OTPs for authentication, verification, and security purposes.

## Features

- 🎯 **Multiple OTP Types**: Numeric, random alphanumeric, and sequenced alphanumeric
- 🔧 **Customizable Length**: Generate OTPs of any length
- 📝 **Case Control**: Upper, lower, or mixed case options
- 🚀 **TypeScript Support**: Full type definitions included
- 📦 **Zero Dependencies**: Lightweight with no external dependencies
- 🛡️ **Secure**: Uses cryptographically secure random generation

## Installation

```bash
npm install @nostrbox/otp-zen
```

## Usage

### Basic Usage

```typescript
import { generateOTP } from '@nostrbox/otp-zen';

// Generate a 6-digit numeric OTP
const numericOTP = generateOTP({
  length: 6,
  type: 'numeric',
});
console.log(numericOTP); // e.g., "123456"

// Generate a 8-character random alphanumeric OTP
const randomOTP = generateOTP({
  length: 8,
  type: 'random-alphanumeric',
  case: 'mixed',
});
console.log(randomOTP); // e.g., "A7b2K9mP"

// Generate a 10-character sequenced alphanumeric OTP
const sequencedOTP = generateOTP({
  length: 10,
  type: 'sequenced-alphanumeric',
  case: 'upper',
});
console.log(sequencedOTP); // e.g., "A1B2C3D4E5"
```

### OTP Types

#### 1. Numeric OTP

Generates OTPs using only numbers (0-9).

```typescript
const otp = generateOTP({
  length: 6,
  type: 'numeric',
});
// Example output: "847392"
```

#### 2. Random Alphanumeric OTP

Generates OTPs using random combinations of letters and numbers.

```typescript
const otp = generateOTP({
  length: 8,
  type: 'random-alphanumeric',
  case: 'mixed', // 'upper', 'lower', or 'mixed'
});
// Example output: "K7mN2pQ9"
```

#### 3. Sequenced Alphanumeric OTP

Generates OTPs with alternating letters and numbers in a specific pattern.

```typescript
const otp = generateOTP({
  length: 10,
  type: 'sequenced-alphanumeric',
  case: 'upper',
});
// Example output: "A1B2C3D4E5" (letter, number, letter, number...)
```

### Case Options

- `'upper'`: All characters in uppercase
- `'lower'`: All characters in lowercase
- `'mixed'`: Mixed case (default for alphanumeric types)

## API Reference

### `generateOTP(options: OTPOptions): string`

Generates an OTP based on the provided options.

#### Parameters

- `options` (OTPOptions): Configuration object for OTP generation
  - `length` (number): The length of the OTP to generate
  - `type` (OTPType): The type of OTP to generate
    - `'numeric'`: Numbers only (0-9)
    - `'random-alphanumeric'`: Random letters and numbers
    - `'sequenced-alphanumeric'`: Alternating letters and numbers
  - `case` (optional): Case formatting
    - `'upper'`: Uppercase
    - `'lower'`: Lowercase
    - `'mixed'`: Mixed case (default)

#### Returns

- `string`: The generated OTP

## Examples

### Authentication Codes

```typescript
// 6-digit SMS verification code
const smsCode = generateOTP({
  length: 6,
  type: 'numeric',
});

// 8-character email verification code
const emailCode = generateOTP({
  length: 8,
  type: 'random-alphanumeric',
  case: 'upper',
});
```

### Security Tokens

```typescript
// 16-character secure token
const secureToken = generateOTP({
  length: 16,
  type: 'random-alphanumeric',
  case: 'mixed',
});

// 12-character API key
const apiKey = generateOTP({
  length: 12,
  type: 'sequenced-alphanumeric',
  case: 'upper',
});
```

## TypeScript Support

This package includes full TypeScript definitions. The main types are:

```typescript
type OTPType = 'numeric' | 'random-alphanumeric' | 'sequenced-alphanumeric';

interface OTPOptions {
  length: number;
  type: OTPType;
  case?: 'upper' | 'lower' | 'mixed';
}
```

## Development

This project uses semantic release for automated versioning and publishing. See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed contribution guidelines.

### Building

```bash
npm run build
```

### Development Mode

```bash
npm run dev
```

### Testing

```bash
# Run tests
npm test

# Run tests with coverage
npm run test:coverage
```

### Code Quality

```bash
# Format code
npm run format

# Lint code
npm run lint
```

## Contributing

Contributions are welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) for details on:

- Commit message conventions (Conventional Commits)
- Development workflow
- Semantic release process
- Pull request guidelines

## Release Process

This project uses [semantic-release](https://semantic-release.gitbook.io/) for automated versioning and publishing:

- **feat**: New features trigger minor version bumps
- **fix**: Bug fixes trigger patch version bumps
- **feat!** or **BREAKING CHANGE**: Breaking changes trigger major version bumps

Releases are automatically published to npm when changes are pushed to the `main` branch.

## License

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