Versioning & Backward Compatibility

// Boundary parser — knows about the API's quirks
class VomoUserParser {
  parseFromApi(raw) {
    return {
      id: this._parseInt(raw.id),
      firstName: raw.first_name ?? null,
      lastName: raw.last_name ?? null,
      fullName: raw.full_name ?? null,
      email: this._parseEmail(raw.email),
      phone: raw.phone ?? null,
      birthday: this._parseDate(raw.birthday),
      gender: raw.gender ?? null,
      userStatus: raw.user_status ?? null,
      membershipRole: raw.membership_role ?? null,
      createdAt: this._parseDateTime(raw.created_at),
      updatedAt: this._parseDateTime(raw.updated_at),
    };
  }

  _parseInt(value) {
    if (value === null || value === undefined) return null;
    if (typeof value === 'number') return value;
    return parseInt(value, 10) || null; // Audit #41: handle string ints
  }

  _parseDateTime(value) {
    if (!value) return null;
    const parsed = new Date(value);
    if (isNaN(parsed.getTime())) return null;
    return parsed;
  }

  _parseDate(value) {
    if (!value) return null;
    // Audit #44: format is "YYYY-MM-DD"
    const parsed = new Date(value + 'T00:00:00Z');
    if (isNaN(parsed.getTime())) return null;
    return parsed;
  }

  _parseEmail(value) {
    return value?.toLowerCase().trim() ?? null;
  }
}

class VomoUserParserV2 extends VomoUserParser {
  // v2 returns proper types; the base parser's defensive coercion still works
  // but we can override for clarity if desired

  _parseInt(value) {
    return value; // v2 returns proper integers; pass through
  }
}

class VomoClient {
  constructor({ token, version = 'v1' }) {
    this.token = token;
    this.version = version;
    this.baseUrl = `https://api.vomo.org/${version}`;
  }

  async get(path) {
    return fetch(`${this.baseUrl}${path}`, {
      headers: { Authorization: `Bearer ${this.token}` },
    });
  }
}

// Default to v1 for now
const client = new VomoClient({ token, version: 'v1' });

// When v2 is available and tested
const v2Client = new VomoClient({ token, version: 'v2' });

async function getClientForCustomer(customerId) {
  const config = await db.getCustomerConfig(customerId);
  const version = config.vomoApiVersion ?? 'v1';
  const token = await credentialStore.getToken(customerId, 'api_call');
  return new VomoClient({ token, version });
}

class TolerantParser {
  parse(raw) {
    const known = {
      id: raw.id,
      first_name: raw.first_name,
      // ... fields you explicitly know about ...
    };

    // Unknown fields are silently ignored
    return known;
  }
}

// ❌ Anti-pattern
class StrictParser {
  parse(raw) {
    const known = ['id', 'first_name', 'last_name', 'email'];
    const unexpected = Object.keys(raw).filter((k) => !known.includes(k));
    if (unexpected.length > 0) {
      throw new Error(`Unknown fields: ${unexpected.join(',')}`);
    }
    return raw;
  }
}

class AwareParser {
  parse(raw, knownFields) {
    const unknown = Object.keys(raw).filter((k) => !knownFields.includes(k));
    if (unknown.length > 0) {
      logger.debug('Unknown fields encountered', { fields: unknown });
    }
    return this._extractKnown(raw, knownFields);
  }
}

async function fetchUserDetail(customerId, userId) {
  const useV2 = await featureFlags.isEnabled('use_vomo_v2', { customerId });
  const client = useV2
    ? new VomoClient({ version: 'v2', token: await getToken(customerId) })
    : new VomoClient({ version: 'v1', token: await getToken(customerId) });

  const response = await client.get(`/users/${userId}`);
  const raw = await response.json();

  return useV2
    ? new VomoUserParserV2().parseFromApi(raw.data)
    : new VomoUserParser().parseFromApi(raw.data);
}

async function fetchWithDeprecationDetection(url, options) {
  const response = await fetch(url, options);

  const deprecation = response.headers.get('Deprecation');
  const sunset = response.headers.get('Sunset');
  const link = response.headers.get('Link'); // Often points to migration docs

  if (deprecation) {
    await db.upsert('api_deprecation_signals', {
      url,
      deprecation_header: deprecation,
      sunset_date: sunset ? new Date(sunset) : null,
      migration_link: link,
      first_seen_at: new Date(),
    });

    // Alert ops if a deprecation we haven't planned for surfaces
    const planned = await db.isDeprecationPlanned(url);
    if (!planned) {
      await alertOps({
        severity: 'low',
        type: 'unhandled_deprecation',
        url,
        sunset,
      });
    }
  }

  return response;
}

describe('VOMO API contract — Users', () => {
  it('returns expected fields on list', async () => {
    const response = await fetch(
      'https://api.vomo.org/v1/users?page=1',
      { headers: { Authorization: `Bearer ${testToken}` } }
    );
    const page = await response.json();

    expect(page).toHaveProperty('data');
    expect(page).toHaveProperty('links.next');
    expect(page).toHaveProperty('meta.total');

    if (page.data.length > 0) {
      const sampleUser = page.data[0];
      expect(sampleUser).toHaveProperty('id');
      expect(sampleUser).toHaveProperty('email');
      expect(sampleUser).toHaveProperty('updated_at');
    }
  });

  it('updated_at is parseable as ISO 8601 datetime', async () => {
    const response = await fetch(/* ... */);
    const page = await response.json();
    if (page.data.length > 0) {
      const parsed = new Date(page.data[0].updated_at);
      expect(parsed.toString()).not.toBe('Invalid Date');
    }
  });

  it('hours field on participations is parseable as float', async () => {
    // The known v1 quirk per audit #40
    const userDetail = await fetchUserDetail(/* ... */);
    if (userDetail.participations?.length > 0) {
      const hours = userDetail.participations[0].hours;
      expect(typeof hours === 'string' || typeof hours === 'number').toBe(true);
      expect(parseFloat(hours)).toBeGreaterThanOrEqual(0);
    }
  });
});

function transformForExternal(vomoUser) {
  return {
    external_id: `vomo-${vomoUser.id}`,
    email: vomoUser.email,
    first_name: vomoUser.first_name ?? 'Unknown',  // Fallback for null
    last_name: vomoUser.last_name ?? '',
    phone: vomoUser.phone || null,                  // Convert empty string to null
    // ...
  };
}

function processWithFallback(vomoUser) {
  // Required: email and ID
  if (!vomoUser.email || !vomoUser.id) {
    return { skipped: true, reason: 'missing_required_fields' };
  }

  // Everything else has defaults
  return externalSystem.upsertUser({
    external_id: `vomo-${vomoUser.id}`,
    email: vomoUser.email.toLowerCase(),
    first_name: vomoUser.first_name?.trim() || 'Unknown',
    last_name: vomoUser.last_name?.trim() || '',
    // ...
  });
}