Gandi Skill

---
name: gandi
description: "Manage Gandi domains, DNS, email, and SSL certificates via the Gandi API"
---

# Gandi Domain Registrar Skill

Comprehensive Gandi domain registrar integration for Moltbot.

**Status:** 🚧 Phase 1 MVP - Basic operations functional

## Current Capabilities (Phase 1)

- ✅ Personal Access Token authentication
- ✅ List domains in your account
- ✅ Get domain details (expiration, status, services)
- ✅ List DNS records for domains
- ✅ View domain and DNS information
- ✅ **Domain availability checking** ([#4](https://github.com/chrisagiddings/moltbot-gandi-skill/issues/4))
- ✅ **Smart domain suggestions with variations** ([#4](https://github.com/chrisagiddings/moltbot-gandi-skill/issues/4))
- ✅ SSL certificate status checker
- ✅ Error handling and validation

## Coming Soon (Phase 2+)

- Domain registration
- DNS record modification (add, update, delete)
- Multi-organization support ([#1](https://github.com/chrisagiddings/moltbot-gandi-skill/issues/1))
- Gateway Console configuration ([#3](https://github.com/chrisagiddings/moltbot-gandi-skill/issues/3))
- Domain renewal management
- DNSSEC configuration
- Certificate management
- Email configuration

## Setup

### Step 1: Create Personal Access Token

1. Go to [Gandi Admin → Personal Access Tokens](https://admin.gandi.net/organizations/account/pat)
2. Click **"Create a token"**
3. Select your organization
4. Choose scopes:
   - ✅ Domain: read (minimum)
   - ✅ LiveDNS: read (for DNS operations)
5. Copy the token (you won't see it again!)

### Step 2: Store Token

```bash
# Create config directory
mkdir -p ~/.config/gandi

# Store your token (replace YOUR_PAT with actual token)
echo "YOUR_PERSONAL_ACCESS_TOKEN" > ~/.config/gandi/api_token

# Secure the file (owner read-only)
chmod 600 ~/.config/gandi/api_token
```

### Step 3: Test Authentication

```bash
cd gandi-skill/scripts
node test-auth.js
```

Expected output:
```
✅ Authentication successful!

Your organizations:
  1. Personal Account (uuid-here)
     Type: individual

🎉 You're ready to use the Gandi skill!
```

### Step 4: Setup Contact Information (Optional, for Domain Registration)

If you plan to register domains, save your contact information once for reuse:

```bash
cd gandi-skill/scripts
node setup-contact.js
```

**The script will prompt for:**
- Name (first and last)
- Email address
- Phone number (international format: +1.5551234567)
- Street address
- City
- State/Province (for US: 2-letter code like OH, automatically formatted to US-OH)
- ZIP/Postal code
- Country (2-letter code: US, FR, etc.)
- Type (individual or company)
- **Privacy preference:** Retain or auto-purge contact after registration

**Contact information is saved to:**
- `~/.config/gandi/contact.json`
- Permissions: 600 (owner read-write only)
- Outside the skill directory (never committed to git)

**Privacy Options:**

1. **RETAIN (default):** Keep contact saved for future registrations
   - Best for frequent domain registrations
   - Setup once, use forever
   - Delete manually anytime with `delete-contact.js`

2. **PURGE:** Auto-delete contact after each registration
   - Best for privacy-conscious users
   - Contact info only exists during registration
   - Must re-enter for next registration

**Managing saved contact:**
```bash
# View current contact
node view-contact.js

# Update contact info or privacy preference
node setup-contact.js

# Delete saved contact manually
node delete-contact.js

# Delete without confirmation
node delete-contact.js --force
```

**One-time purge override:**
```bash
# Register and delete contact (even if preference is "retain")
node register-domain.js example.com --purge-contact
```

## Usage Examples

### List Your Domains

```bash
node list-domains.js
```

Output shows:
- Domain names
- Expiration dates
- Auto-renewal status
- Services (LiveDNS, Email, etc.)
- Organization ownership

### List DNS Records

```bash
node list-dns.js example.com
```

Output shows:
- All DNS records grouped by type
- TTL values
- Record names and values
- Nameservers

### Using from Moltbot

Once configured, you can use natural language:

> "List my Gandi domains"

> "Show DNS records for example.com"

> "When does example.com expire?"

> "Is auto-renewal enabled for example.com?"

## Domain Availability Checking

### Check Single Domain

Check if a specific domain is available for registration:

```bash
node check-domain.js example.com
```

**Features:**
- Shows availability status (available/unavailable/pending/error)
- Displays pricing information (registration, renewal, transfer)
- Lists supported features (DNSSEC, LiveDNS, etc.)
- Shows TLD information

**Example Output:**
```
🔍 Checking availability for: example.com

Domain: example.com

✅ Status: AVAILABLE

💰 Pricing:
  1 year: 12.00 EUR (+ 2.40 tax)
  2 years: 24.00 EUR (+ 4.80 tax)

📋 Supported Features:
  • create
  • dnssec
  • livedns

🌐 TLD Information:
  Extension: com
```

### Smart Domain Suggestions

Find available alternatives with TLD variations and name modifications:

```bash
# Check all configured TLDs + variations
node suggest-domains.js example

# Check specific TLDs only
node suggest-domains.js example --tlds com,net,io

# Skip name variations (only check TLDs)
node suggest-domains.js example --no-variations

# Output as JSON
node suggest-domains.js example --json
```

**Name Variation Patterns:**
1. **Hyphenated**: Adds hyphens between word boundaries (`example` → `ex-ample`)
2. **Abbreviated**: Removes vowels (`example` → `exmpl`)
3. **Prefix**: Adds common prefixes (`example` → `get-example`, `my-example`)
4. **Suffix**: Adds common suffixes (`example` → `example-app`, `example-hub`)
5. **Numbers**: Appends numbers (`example` → `example2`, `example3`)

**Example Output:**
```
🔍 Checking availability for: example

📊 Checking 13 TLDs and generating variations...

═══════════════════════════════════════════════════════
📋 EXACT MATCHES (Different TLDs)
═══════════════════════════════════════════════════════

✅ Available:

  example.net                    12.00 EUR
  example.io                     39.00 EUR
  example.dev                    15.00 EUR

❌ Unavailable:

  example.com                    (unavailable)
  example.org                    (unavailable)

═══════════════════════════════════════════════════════
🎨 NAME VARIATIONS
═══════════════════════════════════════════════════════

Hyphenated:

  ✅ ex-ample.com                12.00 EUR

Prefix:

  ✅ get-example.com             12.00 EUR
  ✅ my-example.com              12.00 EUR

Suffix:

  ✅ example-app.com             12.00 EUR
  ✅ example-io.com              12.00 EUR

═══════════════════════════════════════════════════════
📊 SUMMARY: 8 available domains found
═══════════════════════════════════════════════════════
```

### Configuration

Domain checker configuration is stored in `gandi-skill/config/domain-checker-defaults.json`.

**Structure:**
```json
{
  "tlds": {
    "mode": "extend",
    "defaults": ["com", "net", "org", "info", "io", "dev", "app", "ai", "tech"],
    "custom": []
  },
  "variations": {
    "enabled": true,
    "patterns": ["hyphenated", "abbreviated", "prefix", "suffix", "numbers"],
    "prefixes": ["get", "my", "the", "try"],
    "suffixes": ["app", "hub", "io", "ly", "ai", "hq"],
    "maxNumbers": 3
  },
  "rateLimit": {
    "maxConcurrent": 3,
    "delayMs": 200,
    "maxRequestsPerMinute": 100
  },
  "limits": {
    "maxTlds": 5,
    "maxVariations": 10
  }
}
```

**Rate Limiting & Limits:**
- **maxConcurrent**: Maximum concurrent API requests (default: 3)
- **delayMs**: Delay between requests in milliseconds (default: 200ms)
- **maxRequestsPerMinute**: Hard limit on requests per minute (default: 100, Gandi allows 1000)
- **maxTlds**: Maximum TLDs to check in suggest-domains.js (default: 5)
- **maxVariations**: Maximum name variations to generate (default: 10)

These limits ensure good API citizenship and prevent overwhelming Gandi's API.

**TLD Modes:**
- `"extend"`: Use defaults + custom TLDs (merged list)
- `"replace"`: Use only custom TLDs (ignore defaults)

**Gateway Console Integration:**

When Gateway Console support is added ([#3](https://github.com/chrisagiddings/moltbot-gandi-skill/issues/3)), configuration will be available at:

```yaml
skills:
  entries:
    gandi:
      config:
        domainChecker:
          tlds:
            mode: extend
            defaults: [...]
            custom: [...]
          variations:
            enabled: true
            patterns: [...]
```

See `docs/gateway-config-design.md` for complete configuration architecture.

## Helper Scripts

All scripts are in `gandi-skill/scripts/`:

| Script | Purpose |
|--------|---------|
| `test-auth.js` | Verify authentication works |
| `setup-contact.js` | Save contact info for domain registration (run once) |
| `view-contact.js` | View saved contact information |
| `delete-contact.js` | Delete saved contact (with optional --force) |
| `list-domains.js` | Show all domains in account |
| `list-dns.js <domain>` | Show DNS records for domain |
| `check-domain.js <domain>` | Check single domain availability + pricing |
| `suggest-domains.js <name>` | Smart domain suggestions with variations |
| `check-ssl.js` | Check SSL certificate status for all domains |
| `gandi-api.js` | Core API client (importable) |

## Configuration

### Default Configuration

- **Token file:** `~/.config/gandi/api_token` (API authentication)
- **Contact file:** `~/.config/gandi/contact.json` (domain registration info, optional)
- **API URL:** `https://api.gandi.net` (production)

### Sandbox Testing

To use Gandi's sandbox environment:

```bash
# Create sandbox token at: https://admin.sandbox.gandi.net
echo "YOUR_SANDBOX_TOKEN" > ~/.config/gandi/api_token
echo "https://api.sandbox.gandi.net" > ~/.config/gandi/api_url
```

## Troubleshooting

### Token Not Found

```bash
# Verify file exists
ls -la ~/.config/gandi/api_token

# Should show: -rw------- (600 permissions)
```

### Authentication Failed (401)

- Token is incorrect or expired
- Create new token at Gandi Admin
- Update stored token file

### Permission Denied (403)

- Token doesn't have required scopes
- Create new token with Domain:read and LiveDNS:read
- Verify organization membership

### Domain Not Using LiveDNS

If you get "not using Gandi LiveDNS" error:
1. Log in to Gandi Admin
2. Go to domain management
3. Attach LiveDNS service to the domain

### Rate Limit (429)

Gandi allows 1000 requests/minute. If exceeded:
- Wait 60 seconds
- Reduce frequency of API calls

## API Reference

The skill provides importable functions:

```javascript
import { 
  testAuth,
  listDomains,
  getDomain,
  listDnsRecords,
  getDnsRecord,
  checkAvailability
} from './gandi-api.js';

// Test authentication
const auth = await testAuth();

// List domains
const domains = await listDomains();

// Get domain info
const domain = await getDomain('example.com');

// List DNS records
const records = await listDnsRecords('example.com');

// Get specific DNS record
const record = await getDnsRecord('example.com', '@', 'A');

// Check availability
const available = await checkAvailability(['example.com', 'example.net']);
```

## Security

### Token Storage

✅ **DO:**
- Store at `~/.config/gandi/api_token`
- Use 600 permissions (owner read-only)
- Rotate tokens regularly
- Use minimal required scopes

❌ **DON'T:**
- Commit tokens to repositories
- Share tokens between users
- Give tokens unnecessary permissions
- Store tokens in scripts

### Token Scopes

**Phase 1 (current):**
- Domain: read
- LiveDNS: read

**Phase 2+ (future):**
- Domain: read, write (for registration, renewal)
- LiveDNS: read, write (for DNS modifications)
- Certificate: read (optional, for SSL certs)
- Email: read, write (optional, for email config)

## Architecture

```
gandi-skill/
├── SKILL.md                 # This file
├── references/              # API documentation
│   ├── api-overview.md
│   ├── authentication.md
│   ├── domains.md
│   ├── livedns.md
│   └── setup.md
└── scripts/                 # Helper utilities
    ├── package.json
    ├── gandi-api.js         # Core API client
    ├── test-auth.js         # Test authentication
    ├── list-domains.js      # List domains
    └── list-dns.js          # List DNS records
```

## Development Roadmap

**Phase 1: Read Operations** (✅ Current)
- Authentication with PAT
- List domains
- Get domain details
- List DNS records
- Basic error handling

**Phase 2: DNS Modifications**
- Add DNS records
- Update DNS records
- Delete DNS records
- Bulk DNS operations

**Phase 3: Domain Management**
- Domain registration
- Domain renewal
- Auto-renewal configuration
- Nameserver management

**Phase 4: Multi-Organization** ([#1](https://github.com/chrisagiddings/moltbot-gandi-skill/issues/1))
- Profile-based token management
- Organization selection
- Multiple token support

**Phase 5: Advanced Features**
- DNSSEC management
- Certificate management
- Email/mailbox configuration
- Domain transfer operations

## Contributing

See [Contributing Guide](../../README.md#contributing) in the main README.

## Support

- **Issues:** [GitHub Issues](https://github.com/chrisagiddings/moltbot-gandi-skill/issues)
- **Documentation:** [Reference Guides](./references/)
- **Gandi Support:** [help.gandi.net](https://help.gandi.net/)

## License

MIT License - See [LICENSE](../../LICENSE)