Versioning & Backward Compatibility

// ❌ Fragile — crashes if donor.address is missing or null
const city = donor.address.city;

// ✅ Defensive — works in all three cases
const city = donor.address?.city ?? null;

// ✅ JSON.parse naturally ignores fields not used by your code
const gift = await response.json();
const amount = gift.amount;  // Works whether the response has 50 fields or 60

// ❌ Don't strictly validate against a known field set
function strictParseGift(json) {
  const KNOWN_FIELDS = ['id', 'amount', 'date', ...];
  const parsed = JSON.parse(json);
  for (const key of Object.keys(parsed)) {
    if (!KNOWN_FIELDS.includes(key)) throw new Error(`Unknown field: ${key}`);
  }
  return parsed;
}

const KNOWN_FREQUENCIES = {
  1: 'Annual',
  2: 'Semi-annual',
  4: 'Quarterly',
  12: 'Monthly',
  26: 'Biweekly',
  52: 'Weekly',
  100: 'Continuous',
};

function formatFrequency(integer) {
  const label = KNOWN_FREQUENCIES[integer];
  if (!label) {
    console.warn(`Unknown frequency integer: ${integer}`);
    return `Frequency ${integer}`;  // Fallback label
  }
  return label;
}

function shouldChargeSchedule(schedule) {
  const ACTIVE = 1;
  const CANCELLED = 2;
  const PAUSED = 3;

  if (schedule.status === ACTIVE) return true;
  if (schedule.status === CANCELLED || schedule.status === PAUSED) return false;

  // Unknown status — assume not chargeable to be safe
  console.warn(`Unknown schedule status: ${schedule.status}`);
  return false;
}

function mapGiftForDestination(gift) {
  const base = {
    raise_id: gift.id,
    amount: gift.amount,
    date: gift.date,
    donor_email: gift.donor?.email,
  };

  // Newer field — use if present, otherwise fall back
  if (gift.processingFee !== undefined) {
    base.processing_fee = gift.processingFee;
  }

  // Even newer field — use if present
  if (gift.netRevenue !== undefined) {
    base.net_revenue = gift.netRevenue;
  }

  return base;
}

async function checkFeatureSupport() {
  // Does the gift query response support a `processingFee` field?
  const sample = await fetch(
    'https://prod-api.raisedonors.com/api/Gift/list?Take=1',
    { headers: { Authorization: `Bearer ${token}` } }
  ).then((r) => r.json());

  const supportsFeeData = sample.items[0] && 'processingFee' in sample.items[0];

  return { supportsFeeData };
}

const features = await checkFeatureSupport();

if (features.supportsFeeData) {
  // Use the new fee data
}

function parseRecurringGift(raw) {
  return {
    id: raw.id,
    amount: raw.amount ?? 0,
    currency: raw.currency ?? 'USD',
    frequency: raw.frequency ?? 12,
    status: raw.status ?? null,
    hasPaymentFailed: raw.hasPaymentFailed ?? false,
    successfulCycles: raw.successfulCycles ?? 0,
    expMonthAndYear: raw.expMonthAndYear ?? null,
    paymentInfo: raw.paymentInfo ?? null,
    projectAllocation: raw.projectAllocation ?? [],
    donor: raw.donor ?? null,
    crmKey: raw.crmKey ?? null,
  };
}

function parseGiftWithDriftDetection(raw) {
  const KNOWN_FIELDS = new Set([
    'id', 'amount', 'date', 'donorId', 'donor', 'campaignName',
    'segment', 'projects', 'status', 'modifiedDate',
    /* ... etc ... */
  ]);

  const unknownFields = Object.keys(raw).filter((k) => !KNOWN_FIELDS.has(k));
  if (unknownFields.length > 0) {
    driftMetrics.increment('unknown_fields', { resource: 'gift', fields: unknownFields });
  }

  return parseGift(raw);
}

function formatFrequency(integer) {
  if (!(integer in KNOWN_FREQUENCIES)) {
    driftMetrics.increment('unknown_enum', { type: 'frequency', value: integer });
  }
  return KNOWN_FREQUENCIES[integer] ?? `Frequency ${integer}`;
}

if (response.status === 400 && !isExpected400(problem)) {
  driftMetrics.increment('unexpected_400', { endpoint, problem_type: problem.title });
}

const giftsWithoutDonor = recentGifts.filter((g) => !g.donor?.email).length;
if (giftsWithoutDonor > recentGifts.length * 0.1) {
  driftMetrics.increment('high_null_rate', { field: 'donor.email' });
}