bindman

A DNS record conversion utility that transforms DNS records between various provider formats.

Features

• 🔄 Convert between AWS SES, Cloudflare, Route53, and generic CSV formats
• 📦 Available as both CLI tool and JavaScript/TypeScript library
• 🎨 Colored output with helpful error messages
• 🔧 Extensible provider architecture
• ⚡ Fast - built with Bun/Node.js

Installation

Global CLI Installation

# Using npm
npm install -g bindman

# Using bun
bun install -g bindman

Local Project Installation

# Using npm
npm install bindman

# Using bun
bun install bindman

Using npx (no installation)

npx bindman -i dns-records.csv -t aws-ses -T cloudflare

CLI Usage

# Convert AWS SES CSV to Cloudflare BIND format
bindman -i dns-records.csv -t aws-ses -T cloudflare

# Convert generic CSV to Route53 JSON
bindman -i records.csv -t generic-csv -T route53-json -o output.json

# Show help
bindman --help

CLI Options

Options:
  -v, --version             Display version number
  -i, --input <file>        Input file path (required)
  -t, --input-type <type>   Input format: aws-ses, generic-csv (required)
  -T, --output-type <type>  Output format: cloudflare, route53-json, json (required)
  -o, --output <file>       Output file path (default: output.<ext>)
  -h, --help                Display help for command

Supported Formats

| Input Type | Description | |------------|-------------| | aws-ses | AWS SES CSV export format | | generic-csv | Generic CSV with type, name, value columns |

| Output Type | Description | |-------------|-------------| | cloudflare | BIND zone file format for Cloudflare | | route53-json | AWS Route53 ChangeResourceRecordSets API | | json | Plain JSON format |

Library Usage

TypeScript/JavaScript

import { 
  DNSConverter, 
  AWSSESInputProvider, 
  CloudflareOutputProvider 
} from 'bindman';

const converter = new DNSConverter({
  inputProvider: new AWSSESInputProvider(),
  outputProvider: new CloudflareOutputProvider(),
});

const csvContent = `
Type,Name,Value
CNAME,abc._domainkey.example.com,abc.dkim.amazonses.com
MX,mail.example.com,10 feedback-smtp.us-east-1.amazonses.com
`;

const result = converter.convert(csvContent);
console.log(`Converted ${result.recordCount} records`);
console.log(result.content);

Available Providers

Input Providers:

• AWSSESInputProvider - Parse AWS SES CSV format with special handling for duplicate domain names
• GenericCSVInputProvider - Parse generic CSV format with flexible column names

Output Providers:

• CloudflareOutputProvider - Generate Cloudflare BIND zone file format
• Route53OutputProvider - Generate Route53 JSON format for ChangeResourceRecordSets API
• JSONOutputProvider - Generate pretty-printed JSON

Types:

• UnifiedRecord - Internal DNS record representation
• DNSRecordType - Supported DNS record types
• CLIOptions - CLI configuration options

Utility Functions

import { readFile, writeFile, fileExists, FileError } from 'bindman';

// Read file with proper error handling
const content = readFile('dns-records.csv');

// Write file with auto-create directory
writeFile('output.txt', 'content');

// Check if file exists
const exists = fileExists('dns-records.csv');

Input Format Examples

AWS SES CSV Format

Type,Name,Value
CNAME,abc._domainkey.example.com,abc.dkim.amazonses.com
MX,mail.example.com,10 feedback-smtp.us-east-1.amazonses.com
TXT,mail.example.com,"v=spf1 include:amazonses.com ~all"

Special handling:

• Duplicate domain detection: Automatically fixes domains like mail.example.com.example.com → mail.example.com
• MX priority extraction: Extracts priority from value field (e.g., "10 mail.server.com")

Generic CSV Format

Flexible column names accepted:

• Type: type or Type
• Name: name or Name
• Content: content, Value, or Content
• Priority: priority (optional, for MX records)
• TTL: ttl (optional, defaults to 3600)

type,name,content,ttl
A,example.com,192.168.1.1,3600
CNAME,www.example.com,example.com,3600
MX,mail.example.com,10 mail.server.com,3600

Output Format Examples

Cloudflare (BIND Zone File)

abc._domainkey.example.com    3600    IN    CNAME    abc.dkim.amazonses.com
mail.example.com              3600    IN    MX       10 feedback-smtp.us-east-1.amazonses.com
mail.example.com              3600    IN    TXT      "v=spf1 include:amazonses.com ~all"

Route53 JSON

{
  "Changes": [
    {
      "Action": "UPSERT",
      "ResourceRecordSet": {
        "Name": "abc._domainkey.example.com",
        "Type": "CNAME",
        "TTL": 3600,
        "ResourceRecords": [{"Value": "abc.dkim.amazonses.com"}]
      }
    }
  ]
}

Development

Setup

# Clone the repository
git clone https://github.com/krataib/bindman.git
cd bindman

# Install dependencies
bun install

# Build
bun run build

# Run in development
bun run dev -- -i dns-records.csv -t aws-ses -T cloudflare

Scripts

bun run build        # Build for production
bun run build:watch  # Build with watch mode
bun run typecheck    # Run TypeScript type checking
bun run ci           # Full CI check (typecheck + build)
bun run convert      # Run CLI via source

Project Structure

src/
├── cli/
│   ├── commands/       # CLI command implementations
│   ├── services/       # CLI services (conversion, provider registry)
│   ├── utils/          # CLI utilities (logger, error handler)
│   ├── types.ts        # CLI type definitions
│   └── index.ts        # CLI entry point
├── core/
│   └── converter.ts    # Core DNS conversion logic
├── providers/
│   ├── base.ts         # Base provider interfaces and classes
│   ├── input/          # Input providers
│   └── output/         # Output providers
├── types/
│   └── index.ts        # Shared TypeScript types
├── utils/
│   └── file.ts         # File utilities
├── index.ts            # Library entry point
└── main.ts             # CLI main entry

CI/CD

This project uses GitHub Actions for:

• CI: Build, type-check, and test on every push/PR
• Release: Automatic GitHub releases and npm publishing on version tags

To publish a new version:

# Update version in package.json
npm version patch   # or minor/major

# Push with tags
git push origin main --tags

The release workflow will:

1. Create a GitHub Release with build artifacts
2. Publish the package to npm automatically

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.