Birthdays this month

// Scoutworks → birthdays. https://developers.scoutworks.app/recipes/birthdays

const BASE = 'https://api-demo.scoutworks.app/api/v1';
const DAYS_AHEAD = 31;

// Fills the Birthdays tab. Returns the rows, so the email can use them too.
function birthdays() {
  const today = new Date();
  today.setHours(0, 0, 0, 0);
  const rows = [];

  const members = readAll('/members');
  // A key without members.contacts:read gets no dateOfBirth field at all.
  if (members.length && !('dateOfBirth' in members[0])) {
    throw new Error('This key needs the members.contacts:read scope to read dates of birth.');
  }

  members.forEach(function (m) {
    if (!m.dateOfBirth) return; // No date of birth recorded.
    const parts = m.dateOfBirth.split('-').map(Number);
    let next = new Date(today.getFullYear(), parts[1] - 1, parts[2]);
    if (next < today) next = new Date(today.getFullYear() + 1, parts[1] - 1, parts[2]);
    const days = Math.round((next - today) / 86400000);
    if (days > DAYS_AHEAD) return;

    rows.push([
      Utilities.formatDate(next, Session.getScriptTimeZone(), 'EEE d MMM'),
      safe(m.preferredName || m.firstName),
      safe(m.lastName),
      next.getFullYear() - parts[0],
      safe(m.sections[0] ? m.sections[0].name : ''),
      days,
    ]);
  });

  rows.sort(function (a, b) { return a[5] - b[5]; });
  const table = [['Birthday', 'First name', 'Last name', 'Turns', 'Section', 'Days away']].concat(rows);
  const book = SpreadsheetApp.getActive();
  const sheet = book.getSheetByName('Birthdays') || book.insertSheet('Birthdays');
  sheet.clearContents();
  sheet.getRange(1, 1, table.length, table[0].length).setValues(table);
  sheet.setFrozenRows(1);
  return rows;
}

// Optional: emails the list. Run it from a monthly trigger.
function emailBirthdays() {
  const to = PropertiesService.getScriptProperties().getProperty('SEND_TO') ||
    Session.getEffectiveUser().getEmail();
  const lines = birthdays().map(function (r) {
    return r[0] + ': ' + r[1] + ' ' + r[2] + ' turns ' + r[3] + ' (' + r[4] + ')';
  });
  MailApp.sendEmail(to, 'Birthdays in the next ' + DAYS_AHEAD + ' days',
    lines.length ? lines.join('\n') : 'No birthdays this month.');
}

// Every item in a list, following nextCursor to the last page.
function readAll(path) {
  const items = [];
  let cursor = null;
  do {
    let url = BASE + path + (path.indexOf('?') === -1 ? '?' : '&') + 'limit=200';
    if (cursor) url += '&cursor=' + encodeURIComponent(cursor);
    const body = fetchScoutworks(url);
    items.push.apply(items, body.data);
    cursor = body.nextCursor;
  } while (cursor);
  return items;
}

// Calls the API. Waits and tries again if the rate limit is reached.
function fetchScoutworks(url) {
  const apiKey = PropertiesService.getScriptProperties().getProperty('SCOUTWORKS_API_KEY');
  if (!apiKey) throw new Error('Add SCOUTWORKS_API_KEY in Project Settings → Script Properties.');
  for (let attempt = 0; attempt < 3; attempt++) {
    const res = UrlFetchApp.fetch(url, {
      headers: { Authorization: 'Bearer ' + apiKey },
      muteHttpExceptions: true,
    });
    const body = JSON.parse(res.getContentText());
    if (res.getResponseCode() === 200) return body;
    if (res.getResponseCode() === 429) {
      Utilities.sleep((body.retryAfter || 30) * 1000);
      continue;
    }
    throw new Error(body.error.code + ': ' + body.error.message);
  }
  throw new Error('Scoutworks is still busy. Try again in a minute.');
}

// Stops a name that starts with = + - or @ from running as a formula.
function safe(value) {
  const text = String(value);
  return /^\s*[=+\-@]/.test(text) ? "'" + text : text;
}