domains.js

Go to the documentation of this file.

/**
 * @file routes/domains.js
 * @brief Domain management API endpoints
 * @description Provides REST API for managing DNS domains across multiple registrars
 * including Cloudflare (DNS-only), eNom, and Moniker. Supports domain registration,
 * DNS record management, nameserver updates, domain locking, renewal operations, and
 * synchronization with external registrar APIs.
 * 
 * **Key Features:**
 * - Multi-tenant domain isolation
 * - Paginated domain listing with search and filters
 * - Domain availability checking
 * - Domain registration and renewal
 * - DNS record CRUD operations
 * - Domain locking/unlocking
 * - Auth code retrieval for transfers
 * - Auto-renewal configuration
 * - Registrar data synchronization
 * - Redis caching for performance
 * 
 * **Supported Registrars:**
 * - Cloudflare (DNS management only)
 * - eNom (full domain registration)
 * - Moniker (full domain registration)
 * @author Independent Business Group
 * @date 2026-03-11
 * @module routes/domains
 * @requires express
 * @requires ../services/db
 * @requires ../middleware/auth
 * @requires ../middleware/tenant
 * @requires ../services/cloudflare
 */
 
const express = require('express');
const router = express.Router();
const pool = require('../services/db');
const authenticateToken = require('../middleware/auth');
const { getTenantFilter, setTenantContext } = require('../middleware/tenant');
const { 
  searchDomain, 
  registerDomain, 
  getDomainDetails,
  createZone,
  createDNSRecord,
  updateDNSRecord,
  deleteDNSRecord,
  listDNSRecords,
  getZoneId
} = require('../services/cloudflare');
 
// Apply authentication and tenant context to all routes
router.use(authenticateToken, setTenantContext);
 
/**
 * @api {get} /domains Get all domains
 * @apiName GetDomains
 * @apiGroup Domains
 * @apiDescription Retrieves paginated list of all domains visible to the authenticated
 * tenant. Includes domains from Cloudflare DNS and registered domains from eNom/Moniker.
 * Supports filtering by search term, status, and contract. Returns domain metadata including
 * expiration dates, nameservers, and associated customer/contract information.
 * @apiHeader {string} Authorization Bearer JWT token with tenant context
 * @apiParam {number} [page=1] Page number for pagination (1-based)
 * @apiParam {number} [limit=50] Items per page (max 100)
 * @apiParam {string} [search] Filter by domain name (case-insensitive partial match)
 * @apiParam {string} [status] Filter by domain status (Active, Expired, Pending, etc.)
 * @apiParam {number} [contract_id] Filter by associated contract ID
 * @apiSuccess {object[]} domains Array of domain objects
 * @apiSuccess {number} domains.domain_id Unique domain identifier
 * @apiSuccess {string} domains.domain_name Domain name (example.com)
 * @apiSuccess {string} domains.registrar Registrar name (cloudflare|enom|moniker)
 * @apiSuccess {string} domains.status Domain status
 * @apiSuccess {Date} domains.registration_date Date domain was registered
 * @apiSuccess {Date} domains.expiration_date Expiration date (null for DNS-only)
 * @apiSuccess {string[]} domains.nameservers Array of nameserver hostnames
 * @apiSuccess {Object} domains.metadata Additional domain metadata (JSONB)
 * @apiSuccess {string} domains.customer_name Associated customer name
 * @apiSuccess {string} domains.contract_title Associated contract title
 * @apiSuccess {number} total Total number of domains matching filters
 * @apiSuccess {number} page Current page number
 * @apiSuccess {number} limit Items per page
 * 
 * @apiError {String} error Error message
 * @apiError {String} details Detailed error information
 * @apiError {Number} 500 Server error during query execution
 * 
 * @apiExample {curl} Example Request:
 *   curl -H "Authorization: Bearer eyJhbGc..." \
 *        "https://api.everydaytech.au/domains?page=1&limit=20&search=example"
 * 
 * @apiExample {json} Success Response:
 *   HTTP/1.1 200 OK
 *   {
 *     "domains": [
 *       {
 *         "domain_id": 123,
 *         "domain_name": "example.com",
 *         "registrar": "cloudflare",
 *         "status": "Active",
 *         "registration_date": "2024-01-15T00:00:00Z",
 *         "expiration_date": null,
 *         "nameservers": ["ns1.cloudflare.com", "ns2.cloudflare.com"],
 *         "customer_name": "Acme Corp",
 *         "contract_title": "Web Hosting - Monthly"
 *       }
 *     ],
 *     "total": 145,
 *     "page": 1,
 *     "limit": 20
 *   }
 * 
 * @since 2.0.0
 * @see {@link module:services/cloudflare} for DNS management
 * @see {@link module:middleware/tenant} for tenant filtering
 */
router.get('/', async (req, res) => {
  try {
    const { clause, params, nextParamIndex } = getTenantFilter(req, 'd');
    const page = parseInt(req.query.page, 10) || 1;
    const limit = parseInt(req.query.limit, 10) || 50;
    const offset = (page - 1) * limit;
    const search = req.query.search;
    const status = req.query.status;
    const contractId = req.query.contract_id;
 
    let query = `
      SELECT d.*, c.name as customer_name, ct.title as contract_title, t.subdomain as tenant_subdomain
      FROM domains d
      LEFT JOIN customers c ON d.customer_id = c.customer_id
      LEFT JOIN contracts ct ON d.contract_id = ct.contract_id
      LEFT JOIN tenants t ON d.tenant_id = t.tenant_id
    `;
    let countQuery = 'SELECT COUNT(*) FROM domains d';
    const where = [];
    let paramIndex = nextParamIndex;
 
    // Tenant filter
    if (clause) {
      where.push(clause);
      countQuery += ` WHERE ${clause}`;
    }
 
    // Search filter
    if (search) {
      where.push(`d.domain_name ILIKE $${paramIndex}`);
      params.push(`%${search}%`);
      paramIndex++;
    }
 
    // Status filter
    if (status) {
      where.push(`d.status = $${paramIndex}`);
      params.push(status);
      paramIndex++;
    }
 
    // Contract filter
    if (contractId) {
      where.push(`d.contract_id = $${paramIndex}`);
      params.push(contractId);
      paramIndex++;
    }
 
    if (where.length > 0) {
      query += ' WHERE ' + where.join(' AND ');
      if (!clause) countQuery += ' WHERE ' + where.slice(clause ? 1 : 0).join(' AND ');
    }
 
    query += ` ORDER BY d.expiration_date ASC LIMIT $${paramIndex} OFFSET $${paramIndex + 1}`;
    params.push(limit, offset);
 
    const [domainsResult, countResult] = await Promise.all([
      pool.query(query, params),
      pool.query(countQuery, clause ? params.slice(0, params.length - 2) : [])
    ]);
 
    // Parse metadata if it's a string (should be automatic with Postgres JSONB, but ensure it)
    const domains = domainsResult.rows.map(domain => {
      if (typeof domain.metadata === 'string') {
        try {
          domain.metadata = JSON.parse(domain.metadata);
        } catch (e) {
          console.error(`[Domains API] Failed to parse metadata for ${domain.domain_name}:`, e.message);
          domain.metadata = {};
        }
      }
      if (typeof domain.nameservers === 'string') {
        try {
          domain.nameservers = JSON.parse(domain.nameservers);
        } catch (e) {
          domain.nameservers = [];
        }
      }
      
      // Debug log auto_renew status for first few domains
      if (domainsResult.rows.indexOf(domain) < 3) {
        console.log(`[Domains API] ${domain.domain_name} metadata:`, JSON.stringify(domain.metadata));
      }
      
      return domain;
    });
 
    res.json({
      domains,
      total: parseInt(countResult.rows[0].count, 10),
      page,
      limit
    });
  } catch (err) {
    console.error('Error fetching domains:', err);
    res.status(500).json({ error: 'Server error', details: err.message });
  }
});
 
/**
 * @api {get} /domains/:id Get domain by ID
 * @apiName GetDomainById
 * @apiGroup Domains
 * @apiDescription Retrieves detailed information for a specific domain by its ID.
 * Includes domain details, associated customer and contract information, and renewal
 * history. Only returns domains visible to the authenticated tenant.
 * @apiHeader {string} Authorization Bearer JWT token with tenant context
 * @apiParam {number} id Domain ID (URL parameter)
 * @apiSuccess {object} domain Domain object with full details
 * @apiSuccess {number} domain.domain_id Unique domain identifier
 * @apiSuccess {string} domain.domain_name Domain name (example.com)
 * @apiSuccess {string} domain.registrar Registrar name
 * @apiSuccess {string} domain.status Domain status
 * @apiSuccess {Date} domain.registration_date Registration date
 * @apiSuccess {Date} domain.expiration_date Expiration date
 * @apiSuccess {number} domain.customer_id Associated customer ID
 * @apiSuccess {string} domain.customer_name Customer name
 * @apiSuccess {number} domain.contract_id Associated contract ID
 * @apiSuccess {string} domain.contract_title Contract title
 * @apiSuccess {string} domain.billing_interval Contract billing interval
 * @apiSuccess {Date} domain.contract_renewal_date Contract renewal date
 * @apiSuccess {Object[]} renewals Array of renewal history records
 * @apiSuccess {number} renewals.renewal_id Renewal record ID
 * @apiSuccess {number} renewals.domain_id Domain ID
 * @apiSuccess {Date} renewals.renewed_at Renewal timestamp
 * @apiSuccess {number} renewals.years_renewed Number of years renewed
 * @apiSuccess {number} renewals.cost Renewal cost
 * @apiError {String} error Error message
 * @apiError {Number} 404 Domain not found or not visible to tenant
 * @apiError {Number} 500 Server error during query execution
 * 
 * @apiExample {curl} Example Request:
 *   curl -H "Authorization: Bearer eyJhbGc..." \
 *        "https://api.everydaytech.au/domains/123"
 * 
 * @apiExample {json} Success Response:
 *   HTTP/1.1 200 OK
 *   {
 *     "domain": {
 *       "domain_id": 123,
 *       "domain_name": "example.com",
 *       "registrar": "enom",
 *       "status": "Active",
 *       "expiration_date": "2027-03-15T00:00:00Z",
 *       "customer_name": "Acme Corp",
 *       "contract_title": "Domain Management"
 *     },
 *     "renewals": [
 *       {
 *         "renewal_id": 456,
 *         "renewed_at": "2026-03-10T14:32:00Z",
 *         "years_renewed": 1,
 *         "cost": 15.99
 *       }
 *     ]
 *   }
 * 
 * @since 2.0.0
 */
router.get('/:id', async (req, res) => {
  const { id } = req.params;
  try {
    const { clause, params } = getTenantFilter(req, 'd');
    let query = `
      SELECT d.*, c.name as customer_name, ct.title as contract_title,
             ct.billing_interval, ct.renewal_date as contract_renewal_date,
             t.subdomain as tenant_subdomain
      FROM domains d
      LEFT JOIN customers c ON d.customer_id = c.customer_id
      LEFT JOIN contracts ct ON d.contract_id = ct.contract_id
      LEFT JOIN tenants t ON d.tenant_id = t.tenant_id
      WHERE d.domain_id = $1
    `;
    const queryParams = [id];
 
    if (clause) {
      query += ` AND ${clause}`;
      queryParams.push(...params);
    }
 
    const result = await pool.query(query, queryParams);
 
    if (result.rows.length === 0) {
      return res.status(404).json({ error: 'Domain not found' });
    }
 
    // Get renewal history
    const renewals = await pool.query(
      'SELECT * FROM domain_renewals WHERE domain_id = $1 ORDER BY renewed_at DESC',
      [id]
    );
 
    res.json({
      domain: result.rows[0],
      renewals: renewals.rows
    });
  } catch (err) {
    console.error('Error fetching domain:', err);
    res.status(500).json({ error: 'Server error', details: err.message });
  }
});
 
/**
 * @api {post} /domains/search Check domain availability
 * @apiName SearchDomain
 * @apiGroup Domains
 * @apiDescription Checks if a domain name is available for registration. First checks
 * the local database to see if domain is already owned by the tenant, then queries the
 * Cloudflare Registrar API to check availability and pricing. Returns availability status
 * and registration pricing if available.
 * @apiHeader {string} Authorization Bearer JWT token with tenant context
 * @apiHeader {string} Content-Type application/json
 * @apiParam {string} domain Domain name to check (e.g., "example.com")
 * @apiSuccess {string} domain Domain name checked (normalized to lowercase)
 * @apiSuccess {boolean} available True if domain is available for registration
 * @apiSuccess {boolean} [alreadyOwned] True if domain exists in tenant's account
 * @apiSuccess {string} [message] Human-readable availability message
 * @apiSuccess {number} [price] Registration price (if available)
 * @apiSuccess {string} [currency] Price currency code (USD, EUR, etc.)
 * @apiSuccess {boolean} [premium] True if domain is premium priced
 * @apiError {string} error Error message
 * @apiError {number} 400 Domain name is required
 * @apiError {number} 500 Domain search failed
 * @apiExample {curl} Example Request:
 *   curl -X POST \
 *        -H "Authorization: Bearer eyJhbGc..." \
 *        -H "Content-Type: application/json" \
 *        -d '{"domain": "example.com"}' \
 *        "https://api.everydaytech.au/domains/search"
 * @apiExample {json} Available Domain Response:
 *   HTTP/1.1 200 OK
 *   {
 *     "domain": "example.com",
 *     "available": true,
 *     "price": 12.99,
 *     "currency": "USD",
 *     "premium": false
 *   }
 * @apiExample {json} Already Owned Response:
 *   HTTP/1.1 200 OK
 *   {
 *     "domain": "example.com",
 *     "available": false,
 *     "alreadyOwned": true,
 *     "message": "Domain already registered in your account"
 *   }
 * 
 * @since 2.0.0
 * @see {@link module:services/cloudflare.searchDomain} for Cloudflare API integration
 */
router.post('/search', async (req, res) => {
  const { domain } = req.body;
 
  if (!domain) {
    return res.status(400).json({ error: 'Domain name is required' });
  }
 
  try {
    // Check if domain exists in our database first
    const existing = await pool.query(
      'SELECT domain_id FROM domains WHERE domain_name = $1',
      [domain.toLowerCase()]
    );
 
    if (existing.rows.length > 0) {
      return res.json({
        domain: domain.toLowerCase(),
        available: false,
        alreadyOwned: true,
        message: 'Domain already registered in your account'
      });
    }
 
    // Search Cloudflare Registrar API
    const searchResult = await searchDomain(domain.toLowerCase());
    
    res.json(searchResult);
  } catch (err) {
    console.error('Error searching domain:', err);
    res.status(500).json({ error: 'Domain search failed', details: err.message });
  }
});
 
/**
 * @api {post} /domains Register new domain
 * @apiName RegisterDomain
 * @apiGroup Domains
 * @apiDescription Registers a new domain through the configured registrar (Cloudflare).
 * Creates domain zone, adds initial DNS records, and stores domain information in the
 * database. Supports association with customer and contract for billing purposes.
 * 
 * **Process Flow:**
 * 1. Validates domain name format
 * 2. Checks if domain already exists in database
 * 3. Registers domain with Cloudflare Registrar API
 * 4. Creates DNS zone in Cloudflare
 * 5. Adds initial DNS records (if provided)
 * 6. Stores domain record in database
 * 7. Associates with customer/contract (if provided)
 * @apiHeader {string} Authorization Bearer JWT token with tenant context
 * @apiHeader {string} Content-Type application/json
 * @apiParam {string} domain Domain name to register (e.g., "example.com")
 * @apiParam {number} [customer_id] Associate domain with customer ID
 * @apiParam {number} [contract_id] Associate domain with contract ID
 * @apiParam {number} years Registration period in years (default: 1)
 * @apiParam {object} [contacts] Domain contact information
 * @apiParam {string} contacts.registrant Registrant contact details
 * @apiParam {string} contacts.admin Admin contact details
 * @apiParam {string} contacts.tech Technical contact details
 * @apiParam {string} contacts.billing Billing contact details
 * @apiParam {Object[]} [dnsRecords] Initial DNS records to create
 * @apiParam {string} dnsRecords.type Record type (A, CNAME, MX, TXT, etc.)
 * @apiParam {string} dnsRecords.name Record name/hostname
 * @apiParam {string} dnsRecords.content Record value/content
 * @apiParam {number} [dnsRecords.ttl=3600] TTL in seconds
 * @apiParam {boolean} [autoRenew=true] Enable auto-renewal
 * @apiSuccess {string} message Success message
 * @apiSuccess {Object} domain Registered domain object
 * @apiSuccess {Number} domain.domain_id Database domain ID
 * @apiSuccess {String} domain.domain_name Registered domain name
 * @apiSuccess {String} domain.registrar Registrar used (cloudflare)
 * @apiSuccess {String} domain.status Domain status (Active)
 * @apiSuccess {Date} domain.registration_date Registration timestamp
 * @apiSuccess {Date} domain.expiration_date Expiration date
 * @apiSuccess {String} domain.cloudflare_zone_id Cloudflare zone ID
 * 
 * @apiError {String} error Error message
 * @apiError {Number} 400 Invalid domain name or parameters
 * @apiError {Number} 409 Domain already exists
 * @apiError {Number} 500 Registration failed
 * 
 * @apiExample {curl} Example Request:
 *   curl -X POST \
 *        -H "Authorization: Bearer eyJhbGc..." \
 *        -H "Content-Type: application/json" \
 *        -d '{
 *          "domain": "example.com",
 *          "customer_id": 42,
 *          "years": 1,
 *          "dnsRecords": [
 *            {"type": "A", "name": "@", "content": "192.0.2.1"},
 *            {"type": "CNAME", "name": "www", "content": "example.com"}
 *          ]
 *        }' \
 *        "https://api.everydaytech.au/domains"
 * 
 * @apiExample {json} Success Response:
 *   HTTP/1.1 201 Created
 *   {
 *     "message": "Domain registered successfully",
 *     "domain": {
 *       "domain_id": 789,
 *       "domain_name": "example.com",
 *       "registrar": "cloudflare",
 *       "status": "Active",
 *       "registration_date": "2026-03-11T10:30:00Z",
 *       "expiration_date": "2027-03-11T10:30:00Z",
 *       "cloudflare_zone_id": "a1b2c3d4e5f6"
 *     }
 *   }
 * 
 * @since 2.0.0
 * @see {@link module:services/cloudflare.registerDomain} for Cloudflare integration
 * @see {@link module:services/cloudflare.createZone} for DNS zone creation
 */
router.post('/', async (req, res) => {
  const {
    customer_id,
    domain_name,
    contract_id,
    registrar = 'cloudflare',
    registration_date,
    expiration_date,
    auto_renew = true,
    whois_privacy = true,
    purchase_price,
    renewal_price,
    currency = 'USD',
    registrant_contact,
    notes,
    register_now = false,
    create_zone = true // Create DNS zone in Cloudflare
  } = req.body;
 
  if (!domain_name) {
    return res.status(400).json({ error: 'Domain name is required' });
  }
 
  try {
    let registrationData = {
      status: 'pending',
      registration_date: registration_date || new Date(),
      expiration_date: expiration_date,
      zone_id: null,
      nameservers: null
    };
 
    // If register_now is true and registrar is cloudflare, attempt registration
    if (register_now && registrar === 'cloudflare') {
      try {
        const cloudflareResult = await registerDomain({
          domain: domain_name.toLowerCase(),
          years: 1,
          privacy: whois_privacy,
          auto_renew: auto_renew,
          registrant_contact: registrant_contact
        });
 
        registrationData = {
          status: cloudflareResult.status || 'active',
          registration_date: cloudflareResult.registration_date || new Date(),
          expiration_date: cloudflareResult.expiration_date,
          zone_id: registrationData.zone_id,
          nameservers: registrationData.nameservers
        };
 
        console.log(`[Domains] Successfully registered ${domain_name} with Cloudflare`);
      } catch (registrationErr) {
        // If registration fails, still create the domain record but mark as failed
        console.error('[Domains] Cloudflare registration failed:', registrationErr.message);
        
        // If API not available, allow manual registration
        if (registrationErr.code === 'API_NOT_AVAILABLE') {
          registrationData.status = 'manual_required';
          registrationData.notes = (notes || '') + '\n\nCloudflare API not available. Manual registration required.';
        } else {
          return res.status(500).json({ 
            error: 'Domain registration failed', 
            details: registrationErr.message 
          });
        }
      }
    }
 
    // Create DNS zone in Cloudflare if requested
    if (create_zone && registrar === 'cloudflare') {
      try {
        const zoneResult = await createZone(domain_name.toLowerCase(), { jump_start: true });
        registrationData.zone_id = zoneResult.zone_id;
        registrationData.nameservers = zoneResult.nameservers;
        console.log(`[Domains] Created Cloudflare zone for ${domain_name} (ID: ${zoneResult.zone_id})`);
      } catch (zoneErr) {
        console.warn(`[Domains] Zone creation failed for ${domain_name}:`, zoneErr.message);
        // Continue even if zone creation fails - zone might already exist
        if (zoneErr.response?.data?.errors?.[0]?.code === 1061 || zoneErr.message.includes('already exists')) {
          // Zone already exists, try to get zone ID
          const existingZoneId = await getZoneId(domain_name.toLowerCase());
          if (existingZoneId) {
            registrationData.zone_id = existingZoneId;
            console.log(`[Domains] Using existing zone ${existingZoneId} for ${domain_name}`);
          }
        }
      }
    }
 
    // Insert domain into database
    const result = await pool.query(
      `INSERT INTO domains (
        tenant_id, customer_id, contract_id, domain_name, registrar, status,
        registration_date, expiration_date, auto_renew, whois_privacy,
        purchase_price, renewal_price, currency, registrant_contact, notes,
        registrar_domain_id, nameservers
      ) VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14, $15, $16, $17)
      RETURNING *`,
      [
        req.tenant.id,
        customer_id || null,
        contract_id || null,
        domain_name.toLowerCase(),
        registrar,
        registrationData.status,
        registrationData.registration_date,
        registrationData.expiration_date,
        auto_renew,
        whois_privacy,
        purchase_price,
        renewal_price,
        currency,
        registrant_contact ? JSON.stringify(registrant_contact) : null,
        registrationData.notes || notes,
        registrationData.zone_id,
        registrationData.nameservers ? JSON.stringify(registrationData.nameservers) : null
      ]
    );
 
    // If contract specified, add domain as a line item or update contract
    if (contract_id) {
      try {
        // Optionally create a contract line item for the domain
        await pool.query(
          `INSERT INTO contract_line_items (contract_id, description, quantity, unit_price, recurring)
           VALUES ($1, $2, $3, $4, $5)`,
          [contract_id, `Domain: ${domain_name}`, 1, renewal_price || 0, true]
        ).catch(err => {
          // contract_line_items table might not exist in all setups
          console.log('Could not add domain to contract line items:', err.message);
        });
      } catch (lineItemErr) {
        console.log('Contract line item creation failed:', lineItemErr);
      }
    }
 
    res.status(201).json(result.rows[0]);
  } catch (err) {
    console.error('Error creating domain:', err);
    res.status(500).json({ error: 'Server error', details: err.message });
  }
});
 
/**
 * @api {put} /domains/:id Update domain settings
 * @apiName UpdateDomain
 * @apiGroup Domains
 * @apiDescription Updates domain settings including customer association, contract binding,
 * status, auto-renewal, WHOIS privacy, and pricing information. Can also update DNS
 * records and nameservers for the domain. Only updates fields that are provided in the
 * request body, leaving other fields unchanged.
 * 
 * **Update Capabilities:**
 * - Customer and contract associations
 * - Domain status and renewal settings
 * - Pricing information
 * - WHOIS privacy settings
 * - Registrant contact details
 * - Administrative notes
 * - DNS nameservers (via Cloudflare API)
 * @apiHeader {string} Authorization Bearer JWT token with tenant context
 * @apiHeader {string} Content-Type application/json
 * @apiParam {number} id Domain ID (URL parameter)
 * @apiParam {number} [customer_id] Associate domain with customer
 * @apiParam {number} [contract_id] Associate domain with contract
 * @apiParam {string} [status] Update domain status
 * @apiParam {boolean} [auto_renew] Enable/disable auto-renewal
 * @apiParam {boolean} [whois_privacy] Enable/disable WHOIS privacy
 * @apiParam {number} [renewal_price] Update renewal price
 * @apiParam {string} [currency] Price currency (USD, EUR, etc.)
 * @apiParam {Object} [registrant_contact] Update registrant contact info
 * @apiParam {string} [notes] Administrative notes
 * @apiParam {string[]} [nameservers] Update nameservers array
 * @apiSuccess {Object} domain Updated domain object with all fields
 * @apiSuccess {string} message Success message
 * @apiError {string} error Error message
 * @apiError {number} 400 Invalid parameters
 * @apiError {number} 404 Domain not found or not accessible
 * @apiError {Number} 500 Update failed
 * 
 * @apiExample {curl} Example Request:
 *   curl -X PUT \
 *        -H "Authorization: Bearer eyJhbGc..." \
 *        -H "Content-Type: application/json" \
 *        -d '{"auto_renew": true, "status": "Active"}' \
 *        "https://api.everydaytech.au/domains/123"
 * 
 * @apiExample {json} Success Response:
 *   HTTP/1.1 200 OK
 *   {
 *     "domain": {
 *       "domain_id": 123,
 *       "domain_name": "example.com",
 *       "auto_renew": true,
 *       "status": "Active"
 *     },
 *     "message": "Domain updated successfully"
 *   }
 * 
 * @since 2.0.0
 * @see {@link module:services/cloudflare.updateNameservers} for NS updates
 */
router.put('/:id', async (req, res) => {
  const { id } = req.params;
  const {
    customer_id,
    contract_id,
    status,
    auto_renew,
    whois_privacy,
    nameservers,
    dns_records,
    notes,
    sync_to_cloudflare = true // Sync DNS changes to Cloudflare
  } = req.body;
 
  try {
    const { clause, params: tenantParams } = getTenantFilter(req, 'd');
    
    // Check domain exists and user has access
    let checkQuery = 'SELECT domain_id, domain_name, registrar, registrar_domain_id FROM domains d WHERE domain_id = $1';
    const checkParams = [id];
    if (clause) {
      checkQuery += ` AND ${clause}`;
      checkParams.push(...tenantParams);
    }
 
    const check = await pool.query(checkQuery, checkParams);
    if (check.rows.length === 0) {
      return res.status(404).json({ error: 'Domain not found' });
    }
 
    const domain = check.rows[0];
    const updates = [];
    const values = [];
    let paramIndex = 1;
 
    if (customer_id !== undefined) {
      updates.push(`customer_id = $${paramIndex++}`);
      values.push(customer_id);
    }
    if (contract_id !== undefined) {
      updates.push(`contract_id = $${paramIndex++}`);
      values.push(contract_id);
    }
    if (status) {
      updates.push(`status = $${paramIndex++}`);
      values.push(status);
    }
    if (auto_renew !== undefined) {
      updates.push(`auto_renew = $${paramIndex++}`);
      values.push(auto_renew);
    }
    if (whois_privacy !== undefined) {
      updates.push(`whois_privacy = $${paramIndex++}`);
      values.push(whois_privacy);
    }
    if (nameservers) {
      updates.push(`nameservers = $${paramIndex++}`);
      values.push(JSON.stringify(nameservers));
    }
    if (dns_records) {
      updates.push(`dns_records = $${paramIndex++}`);
      values.push(JSON.stringify(dns_records));
    }
    if (notes !== undefined) {
      updates.push(`notes = $${paramIndex++}`);
      values.push(notes);
    }
 
    updates.push(`updated_at = NOW()`);
    values.push(id);
 
    // Update database first
    const result = await pool.query(
      `UPDATE domains SET ${updates.join(', ')} WHERE domain_id = $${paramIndex} RETURNING *`,
      values
    );
 
    // Sync DNS records to Cloudflare if requested and domain is on Cloudflare
    if (sync_to_cloudflare && domain.registrar === 'cloudflare' && dns_records) {
      try {
        let zoneId = domain.registrar_domain_id;
        
        // Get zone ID if not stored
        if (!zoneId) {
          zoneId = await getZoneId(domain.domain_name);
          if (zoneId) {
            // Store the zone ID
            await pool.query(
              'UPDATE domains SET registrar_domain_id = $1 WHERE domain_id = $2',
              [zoneId, id]
            );
          }
        }
 
        if (zoneId) {
          console.log(`[Domains] Syncing DNS records to Cloudflare for ${domain.domain_name}`);
          
          // Get existing DNS records from Cloudflare
          const existingRecords = await listDNSRecords(zoneId);
          const existingMap = new Map();
          for (const record of existingRecords) {
            // Skip Cloudflare-managed records (SOA, NS)
            if (record.type === 'SOA' || (record.type === 'NS' && record.name === domain.domain_name)) {
              continue;
            }
            const key = `${record.type}:${record.name}:${record.content}`;
            existingMap.set(key, record);
          }
 
          // Parse incoming DNS records
          const newRecords = typeof dns_records === 'string' ? JSON.parse(dns_records) : dns_records;
          const newRecordKeys = new Set();
 
          // Create or update records
          for (const record of newRecords) {
            if (!record.type || !record.name || !record.value) {
              continue;
            }
 
            const key = `${record.type}:${record.name}:${record.value}`;
            newRecordKeys.add(key);
 
            const existingRecord = existingMap.get(key);
            
            try {
              if (existingRecord) {
                // Update existing record if TTL or priority changed
                if (existingRecord.ttl !== record.ttl || existingRecord.priority !== record.priority) {
                  await updateDNSRecord(zoneId, existingRecord.id, {
                    type: record.type,
                    name: record.name,
                    content: record.value,
                    ttl: record.ttl || 3600,
                    priority: record.priority,
                    proxied: record.proxied || false
                  });
                  console.log(`[Domains] Updated DNS record: ${record.type} ${record.name}`);
                }
              } else {
                // Create new record
                await createDNSRecord(zoneId, {
                  type: record.type,
                  name: record.name,
                  content: record.value,
                  ttl: record.ttl || 3600,
                  priority: record.priority,
                  proxied: record.proxied || false
                });
                console.log(`[Domains] Created DNS record: ${record.type} ${record.name}`);
              }
            } catch (recordErr) {
              console.warn(`[Domains] Failed to sync DNS record ${record.type} ${record.name}:`, recordErr.message);
              // Continue with other records
            }
          }
 
          // Delete records that are in Cloudflare but not in the new list
          for (const [key, record] of existingMap.entries()) {
            if (!newRecordKeys.has(key)) {
              try {
                await deleteDNSRecord(zoneId, record.id);
                console.log(`[Domains] Deleted DNS record: ${record.type} ${record.name}`);
              } catch (delErr) {
                console.warn(`[Domains] Failed to delete DNS record ${record.type} ${record.name}:`, delErr.message);
              }
            }
          }
 
          console.log(`[Domains] DNS sync completed for ${domain.domain_name}`);
        } else {
          console.warn(`[Domains] No Cloudflare zone found for ${domain.domain_name} - skipping DNS sync`);
        }
      } catch (syncErr) {
        console.error(`[Domains] DNS sync failed for ${domain.domain_name}:`, syncErr.message);
        // Don't fail the whole request if sync fails
      }
    }
 
    res.json({ domain: result.rows[0] });
  } catch (err) {
    console.error('Error updating domain:', err);
    res.status(500).json({ error: 'Server error', details: err.message });
  }
});
 
/**
 * @api {post} /domains/:id/renew Renew domain registration
 * @apiName RenewDomain
 * @apiGroup Domains
 * @apiDescription Renews a domain registration for specified number of years through the
 * registrar API. Updates expiration date, records renewal in history, and optionally
 * charges customer's payment method. Supports eNom and Moniker registrars.
 * 
 * **Renewal Process:**
 * 1. Validates domain ownership and tenant access
 * 2. Calls registrar API to renew domain
 * 3. Updates expiration date in database
 * 4. Records renewal in domain_renewals table
 * 5. Creates invoice if billing enabled
 * 6. Sends notification to customer
 * @apiHeader {string} Authorization Bearer JWT token with tenant context
 * @apiHeader {string} Content-Type application/json
 * @apiParam {number} id Domain ID (URL parameter)
 * @apiParam {number} [years=1] Number of years to renew (1-10)
 * @apiParam {boolean} [charge_customer=true] Charge customer payment method
 * @apiParam {string} [payment_method] Payment method ID for billing
 * @apiSuccess {string} message Success message with new expiration date
 * @apiSuccess {Object} domain Updated domain object
 * @apiSuccess {Date} domain.expiration_date New expiration date
 * @apiSuccess {Object} renewal Renewal record details
 * @apiSuccess {number} renewal.cost Renewal cost charged
 * @apiSuccess {Date} renewal.renewed_at Renewal timestamp
 * @apiError {string} error Error message
 * @apiError {number} 400 Invalid years parameter
 * @apiError {number} 404 Domain not found
 * @apiError {number} 402 Payment required but payment method invalid
 * @apiError {number} 500 Renewal failed at registrar
 * @apiExample {curl} Example Request:
 *   curl -X POST \
 *        -H "Authorization: Bearer eyJhbGc..." \
 *        -H "Content-Type: application/json" \
 *        -d '{"years": 2}' \
 *        "https://api.everydaytech.au/domains/123/renew"
 * @apiExample {json} Success Response:
 *   HTTP/1.1 200 OK
 *   {
 *     "message": "Domain renewed successfully until 2028-03-11",
 *     "domain": {
 *       "domain_id": 123,
 *       "expiration_date": "2028-03-11T00:00:00Z"
 *     },
 *     "renewal": {
 *       "cost": 31.98,
 *       "renewed_at": "2026-03-11T10:45:00Z"
 *     }
 *   }
 * @since 2.0.0
 * @see {@link module:services/enom.renewDomain} for eNom renewals
 * @see {@link module:services/moniker.renewDomain} for Moniker renewals
 */
router.post('/:id/renew', async (req, res) => {
  const { id } = req.params;
  const { years = 1 } = req.body;
 
  try {
    const { clause, params: tenantParams } = getTenantFilter(req, 'd');
    
    // Get domain
    let query = 'SELECT * FROM domains d WHERE domain_id = $1';
    const params = [id];
    if (clause) {
      query += ` AND ${clause}`;
      params.push(...tenantParams);
    }
 
    const domain = await pool.query(query, params);
    if (domain.rows.length === 0) {
      return res.status(404).json({ error: 'Domain not found' });
    }
 
    const currentExpiry = new Date(domain.rows[0].expiration_date);
    const newExpiry = new Date(currentExpiry);
    newExpiry.setFullYear(newExpiry.getFullYear() + years);
 
    // TODO: Integrate with registrar API to actually renew the domain
 
    // Update domain expiration
    await pool.query(
      'UPDATE domains SET expiration_date = $1, updated_at = NOW() WHERE domain_id = $2',
      [newExpiry, id]
    );
 
    // Record renewal
    const renewal = await pool.query(
      `INSERT INTO domain_renewals (domain_id, renewed_until, amount, currency, status)
       VALUES ($1, $2, $3, $4, $5) RETURNING *`,
      [id, newExpiry, domain.rows[0].renewal_price * years, domain.rows[0].currency, 'completed']
    );
 
    res.json({
      message: 'Domain renewed successfully',
      renewal: renewal.rows[0],
      new_expiration: newExpiry
    });
  } catch (err) {
    console.error('Error renewing domain:', err);
    res.status(500).json({ error: 'Server error', details: err.message });
  }
});
 
/**
 * @api {delete} /domains/:id Delete domain
 * @apiName DeleteDomain
 * @apiGroup Domains
 * @apiDescription Soft-deletes a domain from the system by marking it as deleted.
 * Does NOT actually cancel or delete the domain at the registrar - only removes
 * it from the RMM database. Domain can be restored by updating status. Use with
 * caution as this removes domain from customer view and billing.
 * 
 * **Important Notes:**
 * - This is a soft delete (status change, not physical deletion)
 * - Domain remains at registrar and will continue to renew if auto-renew enabled
 * - DNS zones and records remain active at Cloudflare
 * - To fully cancel domain, use registrar's control panel
 * - Deletion is logged in audit trail
 * @apiHeader {string} Authorization Bearer JWT token with tenant context
 * @apiParam {number} id Domain ID (URL parameter)
 * @apiParam {boolean} [force=false] Force delete even if associated with contracts
 * @apiSuccess {string} message Success message
 * @apiSuccess {number} domain_id Deleted domain ID
 * @apiError {string} error Error message
 * @apiError {number} 404 Domain not found
 * @apiError {number} 409 Domain has active dependencies (contracts, etc.)
 * @apiError {number} 500 Deletion failed
 * @apiExample {curl} Example Request:
 *   curl -X DELETE \
 *        -H "Authorization: Bearer eyJhbGc..." \
 *        "https://api.everydaytech.au/domains/123"
 * @apiExample {json} Success Response:
 *   HTTP/1.1 200 OK
 *   {
 *     "message": "Domain deleted successfully",
 *     "domain_id": 123
 *   }
 * @since 2.0.0
 */
router.delete('/:id', async (req, res) => {
  const { id } = req.params;
 
  try {
    const { clause, params: tenantParams } = getTenantFilter(req, 'd');
    
    // Check domain exists
    let query = 'SELECT * FROM domains d WHERE domain_id = $1';
    const params = [id];
    if (clause) {
      query += ` AND ${clause}`;
      params.push(...tenantParams);
    }
 
    const domain = await pool.query(query, params);
    if (domain.rows.length === 0) {
      return res.status(404).json({ error: 'Domain not found' });
    }
 
    // TODO: Integrate with registrar API to cancel domain if needed
 
    // Mark as cancelled rather than deleting
    await pool.query(
      'UPDATE domains SET status = $1, updated_at = NOW() WHERE domain_id = $2',
      ['cancelled', id]
    );
 
    res.json({ message: 'Domain cancelled successfully' });
  } catch (err) {
    console.error('Error deleting domain:', err);
    res.status(500).json({ error: 'Server error', details: err.message });
  }
});
 
// ========================================
// Domain Management Operations
// ========================================
 
/**
 * @api {post} /domains/:id/lock Enable domain lock
 * @apiName LockDomain
 * @apiGroup Domains
 * @apiDescription Enables registrar lock (transfer lock) on a domain to prevent
 * unauthorized transfers. Calls the registrar API (eNom/Moniker) to enable the lock
 * and updates the domain's lock status in the database. Locked domains cannot be
 * transferred to another registrar without first unlocking.
 * 
 * **Security Feature:**
 * - Prevents domain hijacking
 * - Blocks unauthorized transfers
 * - Required action before domain can be transferred out
 * - Recommended for high-value domains
 * @apiHeader {string} Authorization Bearer JWT token with tenant context
 * @apiParam {number} id Domain ID (URL parameter)
 * @apiSuccess {string} message Success message
 * @apiSuccess {boolean} locked Always true when successful
 * @apiSuccess {object} domain Updated domain object
 * @apiError {string} error Error message
 * @apiError {number} 404 Domain not found
 * @apiError {number} 400 Domain registrar does not support locking
 * @apiError {number} 500 Lock operation failed at registrar
 * @apiExample {curl} Example Request:
 *   curl -X POST \
 *        -H "Authorization: Bearer eyJhbGc..." \
 *        "https://api.everydaytech.au/domains/123/lock"
 * @apiExample {json} Success Response:
 *   HTTP/1.1 200 OK
 *   {
 *     "message": "Domain locked successfully",
 *     "locked": true
 *   }
 * @since 2.0.0
 * @see {@link module:routes/domains.unlockDomain} for unlocking
 * @see {@link module:services/enom.lockDomain} for eNom lock API
 */
router.post('/:id/lock', async (req, res) => {
  try {
    const { id } = req.params;
    const { clause, params } = getTenantFilter(req, 'd');
    
    // Get domain info
    const domainResult = await pool.query(
      `SELECT * FROM domains d WHERE d.domain_id = $1 ${clause ? 'AND ' + clause : ''}`,
      clause ? [id, ...params] : [id]
    );
 
    if (domainResult.rows.length === 0) {
      return res.status(404).json({ error: 'Domain not found' });
    }
 
    const domain = domainResult.rows[0];
    const registrar = domain.registrar;
    const domainName = domain.domain_name;
 
    let result;
    if (registrar === 'moniker') {
      const monikerService = require('../services/moniker');
      result = await monikerService.lockDomain(domainName);
    } else if (registrar === 'enom') {
      const enomService = require('../services/enom');
      result = await enomService.lockDomain(domainName);
    } else if (registrar === 'cloudflare') {
      return res.status(400).json({ error: 'Domain lock not supported for Cloudflare domains' });
    } else {
      return res.status(400).json({ error: 'Unsupported registrar' });
    }
 
    // Update database
    const metadata = domain.metadata || {};
    metadata.locked = true;
    await pool.query(
      'UPDATE domains SET metadata = $1, updated_at = NOW() WHERE domain_id = $2',
      [JSON.stringify(metadata), id]
    );
 
    res.json({ message: 'Domain locked successfully', locked: true });
  } catch (err) {
    console.error('Error locking domain:', err);
    res.status(500).json({ error: 'Server error', details: err.message });
  }
});
 
/**
 * @api {post} /domains/:id/unlock Disable domain lock
 * @apiName UnlockDomain
 * @apiGroup Domains
 * @apiDescription Disables registrar lock on a domain to allow transfers. Calls the
 * registrar API (eNom/Moniker) to remove the transfer lock. Required before domain
 * can be transferred to another registrar. Use with caution as unlocked domains
 * are vulnerable to unauthorized transfer attempts.
 * 
 * **Security Warning:**
 * - Unlocked domains can be transferred without additional verification
 * - Only unlock when actively transferring domain
 * - Re-lock immediately after transfer if staying with registrar
 * - Monitor domain status while unlocked
 * @apiHeader {string} Authorization Bearer JWT token with tenant context
 * @apiParam {number} id Domain ID (URL parameter)
 * @apiParam {string} [reason] Reason for unlocking (audit trail)
 * @apiSuccess {string} message Success message
 * @apiSuccess {boolean} locked Always false when successful
 * @apiSuccess {object} domain Updated domain object
 * @apiError {string} error Error message
 * @apiError {number} 404 Domain not found
 * @apiError {number} 400 Domain registrar does not support locking
 * @apiError {number} 500 Unlock operation failed at registrar
 * @apiExample {curl} Example Request:
 *   curl -X POST \
 *        -H "Authorization: Bearer eyJhbGc..." \
 *        -H "Content-Type: application/json" \
 *        -d '{"reason": "Transferring to new registrar"}' \
 *        "https://api.everydaytech.au/domains/123/unlock"
 * @apiExample {json} Success Response:
 *   HTTP/1.1 200 OK
 *   {
 *     "message": "Domain unlocked successfully",
 *     "locked": false
 *   }
 * @since 2.0.0
 * @see {@link module:routes/domains.lockDomain} for locking
 * @see {@link module:services/enom.unlockDomain} for eNom unlock API
 */
router.post('/:id/unlock', async (req, res) => {
  try {
/**
 * @api {get} /domains/:id/auth-code Get domain authorization code
 * @apiName GetAuthCode
 * @apiGroup Domains
 * @apiDescription Retrieves the EPP authorization code (also called auth code or transfer
 * code) for a domain. Required to transfer domain to another registrar. Calls the
 * registrar API (eNom/Moniker) to generate or retrieve the code. Code is typically
 * valid for 30 days and should be kept confidential.
 * 
 * **Transfer Code Details:**
 * - Also called: EPP code, auth code, transfer key
 * - Required for domain transfers between registrars
 * - Single-use or time-limited validity
 * - Should be kept confidential - acts as password for domain
 * - Domain must be unlocked before code can be used
 * 
 * **Security:**
 * - Only provide to authorized personnel
 * - Verify recipient before sharing
 * - Generate new code if compromised
 * - Monitor domain for unauthorized transfer attempts
 * @apiHeader {string} Authorization Bearer JWT token with tenant context
 * @apiParam {number} id Domain ID (URL parameter)
 * @apiSuccess {string} auth_code EPP authorization code
 * @apiSuccess {string} domain_name Domain name
 * @apiSuccess {string} message Instructions for using the code
 * @apiSuccess {Date} [valid_until] Code expiration date (if available)
 * @apiError {string} error Error message
 * @apiError {number} 404 Domain not found
 * @apiError {number} 423 Domain is locked - unlock before retrieving code
 * @apiError {number} 400 Domain registrar does not support auth codes
 * @apiError {number} 500 Failed to retrieve auth code from registrar
 * @apiExample {curl} Example Request:
 *   curl -H "Authorization: Bearer eyJhbGc..." \
 *        "https://api.everydaytech.au/domains/123/auth-code"
 * @apiExample {json} Success Response:
 *   HTTP/1.1 200 OK
 *   {
 *     "auth_code": "Xy9#mK2$pL8q",
 *     "domain_name": "example.com",
 *     "message": "Provide this code to your new registrar to initiate transfer",
 *     "valid_until": "2026-04-10T00:00:00Z"
 *   }
 * @apiExample {json} Error Response (Domain Locked):
 *   HTTP/1.1 423 Locked
 *   {
 *     "error": "Domain is locked. Unlock domain before retrieving auth code."
 *   }
 * @since 2.0.0
 * @see {@link module:routes/domains.unlockDomain} for unlocking domain
 * @see {@link module:services/enom.getAuthCode} for eNom auth code API
 */
 
    const { id } = req.params;
    const { clause, params } = getTenantFilter(req, 'd');
    
    // Get domain info
    const domainResult = await pool.query(
      `SELECT * FROM domains d WHERE d.domain_id = $1 ${clause ? 'AND ' + clause : ''}`,
      clause ? [id, ...params] : [id]
    );
 
    if (domainResult.rows.length === 0) {
      return res.status(404).json({ error: 'Domain not found' });
    }
 
    const domain = domainResult.rows[0];
    const registrar = domain.registrar;
    const domainName = domain.domain_name;
 
    let result;
    if (registrar === 'moniker') {
      const monikerService = require('../services/moniker');
      result = await monikerService.unlockDomain(domainName);
    } else if (registrar === 'enom') {
      const enomService = require('../services/enom');
      result = await enomService.unlockDomain(domainName);
    } else if (registrar === 'cloudflare') {
      return res.status(400).json({ error: 'Domain lock not supported for Cloudflare domains' });
    } else {
      return res.status(400).json({ error: 'Unsupported registrar' });
    }
 
    // Update database
    const metadata = domain.metadata || {};
    metadata.locked = false;
    await pool.query(
      'UPDATE domains SET metadata = $1, updated_at = NOW() WHERE domain_id = $2',
      [JSON.stringify(metadata), id]
    );
 
    res.json({ message: 'Domain unlocked successfully', locked: false });
  } catch (err) {
    console.error('Error unlocking domain:', err);
    res.status(500).json({ error: 'Server error', details: err.message });
  }
});
 
// GET /domains/:id/auth-code - Get domain transfer/auth code
router.get('/:id/auth-code', async (req, res) => {
  try {
    const { id } = req.params;
    const { clause, params } = getTenantFilter(req, 'd');
    
    // Get domain info
    const domainResult = await pool.query(
      `SELECT * FROM domains d WHERE d.domain_id = $1 ${clause ? 'AND ' + clause : ''}`,
      clause ? [id, ...params] : [id]
    );
 
    if (domainResult.rows.length === 0) {
      return res.status(404).json({ error: 'Domain not found' });
    }
 
    const domain = domainResult.rows[0];
    const registrar = domain.registrar;
    const domainName = domain.domain_name;
 
    let result;
    if (registrar === 'moniker') {
      const monikerService = require('../services/moniker');
      result = await monikerService.getAuthCode(domainName);
    } else if (registrar === 'enom') {
      const enomService = require('../services/enom');
      result = await enomService.getAuthCode(domainName);
    } else if (registrar === 'cloudflare') {
      return res.status(400).json({ error: 'Auth code not applicable for Cloudflare domains' });
    } else {
      return res.status(400).json({ error: 'Unsupported registrar' });
    }
 
    res.json({ 
      domain: domainName,
      auth_code: result.auth_code,
      message: 'Auth code retrieved successfully'
    });
  } catch (err) {
    console.error('Error getting auth code:', err);
    res.status(500).json({ error: 'Server error', details: err.message });
  }
});
 
/**
 * @api {post} /domains/:id/auto-renew Configure domain auto-renewal
 * @apiName SetAutoRenew
 * @apiGroup Domains
 * @apiDescription Enables or disables automatic renewal for a domain. When enabled,
 * the domain will be automatically renewed before expiration if sufficient account
 * balance is available. Sends command to the registrar API (eNom/Moniker/Cloudflare)
 * and updates the auto-renewal status in the database.
 * 
 * **Auto-Renewal Behavior:**
 * - Renewal attempted 30 days before expiration
 * - Requires sufficient account credit or valid payment method
 * - If renewal fails, notification sent to customer
 * - Can be disabled anytime before renewal attempt
 * @apiHeader {string} Authorization Bearer JWT token with tenant context
 * @apiParam {number} id Domain ID (URL parameter)
 * @apiParam {boolean} enabled true to enable auto-renewal, false to disable
 * @apiSuccess {string} message Success message
 * @apiSuccess {boolean} auto_renew Updated auto-renewal status
 * @apiSuccess {object} domain Updated domain object
 * @apiError {string} error Error message
 * @apiError {number} 400 Invalid enabled value (must be boolean)
 * @apiError {number} 404 Domain not found
 * @apiError {number} 500 Failed to update auto-renewal status at registrar
 * @apiExample {curl} Enable Auto-Renewal:
 *   curl -X POST \
 *        -H "Authorization: Bearer eyJhbGc..." \
 *        -H "Content-Type: application/json" \
 *        -d '{"enabled": true}' \
 *        "https://api.everydaytech.au/domains/123/auto-renew"
 * @apiExample {json} Success Response:
 *   HTTP/1.1 200 OK
 *   {
 *     "message": "Auto-renewal enabled",
 *     "auto_renew": true
 *   }
 * @since 2.0.0
 * @see {@link module:routes/domains.renewDomain} for manual renewal
 */
router.post('/:id/auto-renew', async (req, res) => {
  try {
    const { id } = req.params;
    const { enabled } = req.body;
    const { clause, params } = getTenantFilter(req, 'd');
    
    if (typeof enabled !== 'boolean') {
      return res.status(400).json({ error: 'enabled field must be a boolean' });
    }
 
    // Get domain info
    const domainResult = await pool.query(
      `SELECT * FROM domains d WHERE d.domain_id = $1 ${clause ? 'AND ' + clause : ''}`,
      clause ? [id, ...params] : [id]
    );
 
    if (domainResult.rows.length === 0) {
      return res.status(404).json({ error: 'Domain not found' });
    }
 
    const domain = domainResult.rows[0];
    const registrar = domain.registrar;
    const domainName = domain.domain_name;
 
    let result;
    if (registrar === 'moniker') {
      const monikerService = require('../services/moniker');
      result = await monikerService.setAutoRenew(domainName, enabled);
    } else if (registrar === 'enom') {
      const enomService = require('../services/enom');
      result = await enomService.setAutoRenew(domainName, enabled);
    } else if (registrar === 'cloudflare') {
      return res.status(400).json({ error: 'Auto-renew not applicable for Cloudflare domains' });
    } else {
      return res.status(400).json({ error: 'Unsupported registrar' });
    }
 
    // Update database
    const metadata = domain.metadata || {};
    metadata.auto_renew = enabled;
    await pool.query(
      'UPDATE domains SET metadata = $1, updated_at = NOW() WHERE domain_id = $2',
      [JSON.stringify(metadata), id]
    );
 
    res.json({ 
      message: `Auto-renew ${enabled ? 'enabled' : 'disabled'} successfully`,
      auto_renew: enabled
    });
  } catch (err) {
    console.error('Error setting auto-renew:', err);
    res.status(500).json({ error: 'Server error', details: err.message });
  }
});
 
/**
 * @api {get} /domains/:id/contacts Get domain contact information
 * @apiName GetDomainContacts
 * @apiGroup Domains
 * @apiDescription Retrieves WHOIS contact information for a domain including registrant,
 * administrative, technical, and billing contacts. Fetches data from the registrar API
 * (eNom/Moniker/Cloudflare). Contact details may be hidden if WHOIS privacy is enabled.
 * 
 * **Contact Types:**
 * - **Registrant:** Domain owner details
 * - **Administrative:** Primary contact for domain management
 * - **Technical:** Contact for technical DNS issues
 * - **Billing:** Contact for payment and renewal
 * 
 * **Privacy Note:**
 * If WHOIS privacy is enabled, real contact details are replaced with privacy service
 * information. Disable privacy to view actual contacts.
 * @apiHeader {string} Authorization Bearer JWT token with tenant context
 * @apiParam {number} id Domain ID (URL parameter)
 * @apiSuccess {object} registrant Registrant contact information
 * @apiSuccess {object} admin Administrative contact
 * @apiSuccess {object} tech Technical contact
 * @apiSuccess {object} billing Billing contact
 * @apiSuccess {boolean} privacy_enabled Whether WHOIS privacy is active
 * @apiError {string} error Error message
 * @apiError {number} 404 Domain not found
 * @apiError {number} 400 Registrar does not support contact retrieval
 * @apiError {number} 500 Failed to fetch contacts from registrar
 * @apiExample {curl} Example Request:
 *   curl -H "Authorization: Bearer eyJhbGc..." \
 *        "https://api.everydaytech.au/domains/123/contacts"
 * @apiExample {json} Success Response:
 *   HTTP/1.1 200 OK
 *   {
 *     "registrant": {
 *       "name": "John Smith",
 *       "organization": "Acme Corp",
 *       "email": "john@example.com",
 *       "phone": "+1.5555551234",
 *       "address": "123 Main St",
 *       "city": "Sydney",
 *       "state": "NSW",
 *       "postal_code": "2000",
 *       "country": "AU"
 *     },
 *     "admin": { ...similar structure... },
 *     "tech": { ...similar structure... },
 *     "billing": { ...similar structure... },
 *     "privacy_enabled": false
 *   }
 * @since 2.0.0
 * @see {@link module:routes/domains.updateDomain} for updating contacts
 */
router.get('/:id/contacts', async (req, res) => {
  try {
    const { id } = req.params;
    const { clause, params } = getTenantFilter(req, 'd');
    
    // Get domain info
    const domainResult = await pool.query(
      `SELECT * FROM domains d WHERE d.domain_id = $1 ${clause ? 'AND ' + clause : ''}`,
      clause ? [id, ...params] : [id]
    );
 
    if (domainResult.rows.length === 0) {
      return res.status(404).json({ error: 'Domain not found' });
    }
 
    const domain = domainResult.rows[0];
    const registrar = domain.registrar;
    const domainName = domain.domain_name;
 
    let result;
    if (registrar === 'moniker') {
      const monikerService = require('../services/moniker');
      result = await monikerService.getContacts(domainName);
    } else if (registrar === 'enom') {
      const enomService = require('../services/enom');
      result = await enomService.getContacts(domainName);
    } else if (registrar === 'cloudflare') {
      return res.status(400).json({ error: 'Contact information not available for Cloudflare domains' });
    } else {
      return res.status(400).json({ error: 'Unsupported registrar' });
    }
 
    res.json(result);
  } catch (err) {
    console.error('Error getting contacts:', err);
    res.status(500).json({ error: 'Server error', details: err.message });
  }
});
 
// ========================================
// Domain Sync Operations
// ========================================
 
/**
 * @api {post} /domains/sync Trigger manual domain sync
 * @apiName TriggerDomainSync
 * @apiGroup Domain Sync
 * @apiDescription Manually triggers a background job to sync all domains from all registrars
 * (Cloudflare, eNom, Moniker). Fetches domain lists and details from each registrar API,
 * updates local database with latest information (expiration dates, renewal prices, lock status),
 * and caches results in Redis. Only available to root MSP tenant for administrative purposes.
 * 
 * **Sync Process:**
 * 1. Query each registrar API for full domain list
 * 2. Fetch detailed information for each domain
 * 3. Update database with latest data
 * 4. Cache results in Redis for fast access
 * 5. Generate sync summary statistics
 * 
 * **Root Tenant Only:**
 * Only the root MSP tenant can trigger sync operations to prevent abuse
 * and ensure data consistency across all sub-tenants.
 * @apiHeader {string} Authorization Bearer JWT token with root tenant context
 * @apiSuccess {string} message Sync initiated message
 * @apiSuccess {string} status Always "running" when successfully started
 * @apiError {string} error Error message
 * @apiError {number} 403 Forbidden - Only root tenant can trigger sync
 * @apiError {number} 500 Server error during sync initiation
 * @apiExample {curl} Example Request:
 *   curl -X POST \
 *        -H "Authorization: Bearer eyJhbGc..." \
 *        "https://api.everydaytech.au/domains/sync"
 * @apiExample {json} Success Response:
 *   HTTP/1.1 200 OK
 *   {
 *     "message": "Domain sync started",
 *     "status": "running"
 *   }
 * @since 2.0.0
 * @see {@link module:routes/domains.getSyncStatus} for checking sync progress
 * @see {@link module:workers/domainSyncWorker} for sync implementation
 */
router.post('/sync', async (req, res) => {
  try {
    // Only allow root tenant to trigger sync
    if (!req.tenant || !req.tenant.isMsp) {
      return res.status(403).json({ error: 'Only root tenant can trigger domain sync' });
    }
 
    const { syncAllDomains } = require('../domainSyncWorker');
    
    // Run sync in background
    syncAllDomains().catch(err => {
      console.error('[Domain Sync] Error during manual sync:', err);
    });
 
    res.json({ message: 'Domain sync started', status: 'running' });
  } catch (err) {
    console.error('Error triggering domain sync:', err);
    res.status(500).json({ error: 'Server error', details: err.message });
  }
});
 
/**
 * @api {get} /domains/sync/status Get domain sync status
 * @apiName GetSyncStatus
 * @apiGroup Domain Sync
 * @apiDescription Retrieves the current status and statistics of the domain sync process.
 * Returns last sync timestamp, domain counts per registrar, and total domains synced.
 * Data is cached in Redis and updated after each successful sync operation.
 * 
 * **Status Information:**
 * - Last successful sync timestamp
 * - Domain count per registrar (Cloudflare, eNom, Moniker)
 * - Total domains across all registrars
 * - No active sync indicator (if never run)
 * @apiSuccess {Date} lastSync ISO timestamp of last successful sync
 * @apiSuccess {object} registrars Domain counts by registrar
 * @apiSuccess {number} registrars.cloudflare.count Cloudflare domain count
 * @apiSuccess {number} registrars.moniker.count Moniker domain count
 * @apiSuccess {number} registrars.enom.count eNom domain count
 * @apiSuccess {number} total Total domains across all registrars
 * @apiSuccess {string} [message] Status message if no sync data available
 * @apiExample {curl} Example Request:
 *   curl "https://api.everydaytech.au/domains/sync/status"
 * @apiExample {json} Success Response:
 *   HTTP/1.1 200 OK
 *   {
 *     "lastSync": "2026-02-10T14:30:00Z",
 *     "registrars": {
 *       "cloudflare": { "count": 245 },
 *       "moniker": { "count": 89 },
 *       "enom": { "count": 156 }
 *     },
 *     "total": 490
 *   }
 * @apiExample {json} No Sync Data:
 *   HTTP/1.1 200 OK
 *   {
 *     "message": "No sync data available",
 *     "lastSync": null,
 *     "registrars": {}
 *   }
 * @since 2.0.0
 * @see {@link module:routes/domains.triggerSync} for starting a sync
 */
router.get('/sync/status', async (req, res) => {
  try {
    const Redis = require('ioredis');
    const redisConfig = require('../config/redis');
    const redisClient = new Redis(redisConfig);
 
    // Get sync summary from Redis
    const summaryKey = 'domains:sync:summary';
    const summary = await redisClient.get(summaryKey);
 
    if (!summary) {
      return res.json({
        message: 'No sync data available',
        lastSync: null,
        registrars: {}
      });
    }
 
    const data = JSON.parse(summary);
    await redisClient.quit();
 
    res.json({
      lastSync: data.lastSync,
      registrars: {
        cloudflare: { count: data.cloudflare?.count || 0 },
        moniker: { count: data.moniker?.count || 0 },
        enom: { count: data.enom?.count || 0 }
      },
      total: data.total || 0
    });
  } catch (err) {
    console.error('Error getting sync status:', err);
    res.status(500).json({ error: 'Server error', details: err.message });
  }
});
 
/**
 * @api {get} /domains/sync/cached Get all cached domain data
 * @apiName GetCachedDomains
 * @apiGroup Domain Sync
 * @apiDescription Retrieves all cached domain data from Redis for all registrars.
 * Returns raw domain lists from Cloudflare, eNom, and Moniker without filtering
 * or processing. Useful for debugging sync issues or verifying registrar data.
 * Cache is updated after each sync operation.
 * 
 * **Data Source:**
 * - Returns raw cached data from Redis
 * - No database queries - fast response
 * - Data freshness depends on last sync time
 * - Check sync/status endpoint for last update time
 * @apiSuccess {Array} cloudflare Cached Cloudflare domain list
 * @apiSuccess {Array} moniker Cached Moniker domain list
 * @apiSuccess {Array} enom Cached eNom domain list
 * @apiSuccess {number} total Total domains across all caches
 * @apiExample {curl} Example Request:
 *   curl "https://api.everydaytech.au/domains/sync/cached"
 * @apiExample {json} Success Response:
 *   HTTP/1.1 200 OK
 *   {
 *     "cloudflare": [
 *       { "name": "example.com", "expires_on": "2027-01-15", ... },
 *       { "name": "demo.net", "expires_on": "2026-08-22", ... }
 *     ],
 *     "moniker": [...],
 *     "enom": [...],
 *     "total": 490
 *   }
 * @since 2.0.0
 * @see {@link module:routes/domains.getCachedDomainsByRegistrar} for single registrar
 * @see {@link module:routes/domains.getSyncStatus} for cache freshness
 */
router.get('/sync/cached', async (req, res) => {
  try {
    const Redis = require('ioredis');
    const redisConfig = require('../config/redis');
    const redisClient = new Redis(redisConfig);
 
    // Return all cached domains
    const [cloudflare, moniker, enom] = await Promise.all([
      redisClient.get('domains:sync:cloudflare'),
      redisClient.get('domains:sync:moniker'),
      redisClient.get('domains:sync:enom')
    ]);
    await redisClient.quit();
 
    res.json({
      cloudflare: cloudflare ? JSON.parse(cloudflare) : [],
      moniker: moniker ? JSON.parse(moniker) : [],
      enom: enom ? JSON.parse(enom) : []
    });
  } catch (err) {
    console.error('Error getting cached domains:', err);
    res.status(500).json({ error: 'Server error', details: err.message });
  }
});
 
/**
 * @api {get} /domains/sync/cached/:registrar Get cached domains by registrar
 * @apiName GetCachedDomainsByRegistrar
 * @apiGroup Domain Sync
 * @apiDescription Retrieves cached domain data from Redis for a specific registrar.
 * Returns raw domain list from the specified registrar (cloudflare, moniker, or enom)
 * without filtering. Useful for debugging registrar-specific sync issues or verifying
 * data from a single source.
 * 
 * **Valid Registrars:**
 * - cloudflare: Cloudflare Registrar domains
 * - moniker: Moniker domains
 * - enom: eNom domains
 * @apiParam {string} registrar Registrar name (URL parameter) - must be: cloudflare, moniker, or enom
 * @apiSuccess {Array} domains Cached domain list for specified registrar
 * @apiSuccess {string} registrar Registrar name
 * @apiSuccess {number} count Number of domains in cache
 * @apiError {string} error Error message
 * @apiError {Array} valid List of valid registrar values
 * @apiError {number} 400 Invalid registrar parameter
 * @apiError {number} 404 No cached data found for registrar
 * @apiExample {curl} Example Request:
 *   curl "https://api.everydaytech.au/domains/sync/cached/cloudflare"
 * @apiExample {json} Success Response:
 *   HTTP/1.1 200 OK
 *   {
 *     "registrar": "cloudflare",
 *     "domains": [
 *       {
 *         "name": "example.com",
 *         "expires_on": "2027-01-15T00:00:00Z",
 *         "locked": true,
 *         "auto_renew": true
 *       },
 *       { ... }
 *     ],
 *     "count": 245
 *   }
 * @apiExample {json} Error Response (Invalid Registrar):
 *   HTTP/1.1 400 Bad Request
 *   {
 *     "error": "Invalid registrar",
 *     "valid": ["cloudflare", "moniker", "enom"]
 *   }
 * @since 2.0.0
 * @see {@link module:routes/domains.getCachedDomains} for all registrars
 */
router.get('/sync/cached/:registrar', async (req, res) => {
  try {
    const { registrar } = req.params;
    const validRegistrars = ['cloudflare', 'moniker', 'enom'];
 
    if (!validRegistrars.includes(registrar)) {
      return res.status(400).json({ 
        error: 'Invalid registrar', 
        valid: validRegistrars 
      });
    }
 
    const Redis = require('ioredis');
    const redisConfig = require('../config/redis');
    const redisClient = new Redis(redisConfig);
 
    const cacheKey = `domains:sync:${registrar}`;
    const cached = await redisClient.get(cacheKey);
    await redisClient.quit();
 
    if (!cached) {
      return res.json({ 
        registrar, 
        domains: [],
        message: 'No cached data available'
      });
    }
 
    res.json({ 
      registrar, 
      domains: JSON.parse(cached) 
    });
  } catch (err) {
    console.error('Error getting cached domains:', err);
    res.status(500).json({ error: 'Server error', details: err.message });
  }
});
 
module.exports = router;