gandi

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)
• ✅ Smart domain suggestions with variations (#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)
• Gateway Console configuration (#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
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

# 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

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:

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:

# 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:

# Register and delete contact (even if preference is "retain")
node register-domain.js example.com --purge-contact

Usage Examples

List Your Domains

node list-domains.js

Output shows:

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

List DNS Records

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:

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:

# 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:

{
  "tlds": {
    "mode": "extend",
    "defaults": ["com", "net", "org", "info", "io", "dev", "app", "ai", "tech"],
    "custom": []
  },
  "variations": {
    "enabled": true,
    "patterns": ["hyphenated", "abbreviated", "prefix", "suffix", "numbers"],
    "prefixes":    
          
     
  
   
     
     
     
  
   
     
     
  

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), configuration will be available at:

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:

# 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

# 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:

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)

• 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 in the main README.

Support

• Issues: GitHub Issues
• Documentation: Reference Guides
• Gandi Support: help.gandi.net

License

MIT License - See LICENSE