Versioning & Backward Compatibility

const CRM_BASE_URL = 'https://api.virtuoussoftware.com';

const ENDPOINTS = {
  contact: '/api/Contact',
  contactQuery: '/api/Contact/Query',
  contactTransaction: '/api/Contact/Transaction',
  gift: '/api/Gift',
  giftTransaction: '/api/v2/Gift/Transaction',    // v2 is the recommended path
  giftQuery: '/api/Gift/Query',
  pledge: '/api/v2/Pledge',                       // entire family is on v2
  pledgeQuery: '/api/v2/Pledge/Query',
  // ...
};

async function virtuousCall(endpointKey, init = {}) {
  const url = `${CRM_BASE_URL}${ENDPOINTS[endpointKey]}`;
  return fetch(url, init);
}

// Cache the feature-detection result per customer
async function supportsBatchGiftTransactions(customerId) {
  const cached = featureCache.get(`${customerId}:batch_gift_tx`);
  if (cached !== undefined) return cached;

  try {
    // Probe with a known-good empty-batch request
    const response = await fetch(
      'https://api.virtuoussoftware.com/api/v2/Gift/Transactions',
      {
        method: 'POST',
        headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
        body: JSON.stringify({ transactions: [] }),
      }
    );
    const supported = response.status !== 404;
    featureCache.set(`${customerId}:batch_gift_tx`, supported);
    return supported;
  } catch {
    return false;
  }
}

// ✅ Good — picks the fields you care about, ignores others
function extractContactSummary(virtuousContact) {
  return {
    id: virtuousContact.id,
    name: virtuousContact.name,
    email: extractPrimaryEmail(virtuousContact),
    modifiedAt: virtuousContact.modifiedDateTimeUtc,
  };
}

// ❌ Bad — strict shape matching that breaks on additions
const ContactSchema = z.object({ /* every documented field */ }).strict();
const contact = ContactSchema.parse(virtuousContact);   // throws on unexpected fields

function parseBoolean(value) {
  if (typeof value === 'boolean') return value;
  if (value === 'true' || value === 'True') return true;
  if (value === 'false' || value === 'False') return false;
  return null;
}

function parseAmount(value) {
  if (typeof value === 'number') return value;
  if (typeof value === 'string') return parseFloat(value);
  return null;
}

function checkDeprecationHeaders(response, endpoint) {
  const sunset = response.headers.get('Sunset');
  const deprecation = response.headers.get('Deprecation');

  if (sunset || deprecation) {
    metrics.increment(`virtuous_deprecated_endpoint`, { endpoint, sunset });
    console.warn(`Deprecated endpoint used: ${endpoint}`, { sunset, deprecation });
  }
}