Skip to content

The OSINT investigator's workbench. One case, one folder, every tool. Local-first: your media and your investigations never leave your machine.

JavaScript
6.2 KB
Raw Blame
/**
 * What to ask NASA FIRMS for, as the Layers panel asks it.
 *
 * The layer answers two different questions with the same marks. **Live** is
 * the last day, three days or week, which FIRMS keeps as layers of its own.
 * **A date** is the archive, which is the same detections asked with a range —
 * and it is the half a case actually needs: whether that field, that depot,
 * that street was burning on the day in question.
 *
 * Everything here is arithmetic over the analyst's choice, so the range rules
 * are read off a test rather than off a map (`firms.test.js`). The key, the
 * WMS and the tiles are the backend's (`engine/firms.py`); the browser never
 * sees any of them.
 */

/** The rolling windows, newest first — what "live" can mean. */
export const WINDOWS = [
  { id: '24h', label: '24 h' },
  { id: '48h', label: '48 h' },
  { id: '72h', label: '72 h' },
  { id: '7d', label: '7 days' },
];

/** Asking by date rather than by how recent. Not a window: a question. */
export const DATED = 'dates';

/**
 * Following the picture on screen: the detections of the day it was taken.
 * Offered by a map that knows its picture's date, since those are the fires the
 * picture can show.
 */
export const PICTURE = 'picture';

/**
 * The choice as the tiles read it, a followed window turned into its day.
 *
 * A picture with no date falls back to the last 24 hours rather than drawing
 * nothing, and the summary says which of the two is on.
 */
export function onDay(choice = {}, day = '') {
  if (choice.window !== PICTURE) return choice;
  const start = asDay(day);
  return start
    ? { ...choice, window: DATED, first: start, last: '' }
    : { ...choice, window: '24h', first: '', last: '' };
}

/** FIRMS refuses a longer range, and counts a long one as several requests. */
export const MAX_RANGE_DAYS = 31;

/** `YYYY-MM-DD`, the only form the service and the input agree on. */
export function asDay(value) {
  return /^\d{4}-\d{2}-\d{2}$/.test(String(value ?? '')) ? String(value) : '';
}

/** Today, in the same form — what an empty date field opens on. */
export function today(now = new Date()) {
  return now.toISOString().slice(0, 10);
}

/**
 * The end of a range the service will accept, given where it starts.
 *
 * Returned rather than enforced, so the panel can say what the limit is on the
 * input itself instead of refusing a date after it was typed.
 */
export function lastDayOf(first, maxDays = MAX_RANGE_DAYS) {
  const start = asDay(first);
  if (!start) return '';
  const end = new Date(`${start}T00:00:00Z`);
  end.setUTCDate(end.getUTCDate() + maxDays - 1);
  return end.toISOString().slice(0, 10);
}

/**
 * Is this choice one the service can answer?
 *
 * A dated window with no date is the normal state of a panel someone has just
 * switched to Dates, not an error — so the layer waits rather than asking for
 * tiles that would come back as an exception report.
 */
export function askable({ window, first, last } = {}) {
  if (window !== DATED) return WINDOWS.some((entry) => entry.id === window);
  const start = asDay(first);
  if (!start) return false;
  const end = asDay(last) || start;
  if (end < start) return false;
  return end <= lastDayOf(start);
}

/**
 * …and the query the tile route is asked with.
 *
 * A rolling window carries no dates: they would be two more things to keep in
 * step with a layer that already means "the last 24 hours".
 */
export function tileParams({ sensor, window, first, last } = {}) {
  if (window !== DATED) return { sensor, window };
  const start = asDay(first);
  return { sensor, window: DATED, first: start, last: asDay(last) || start };
}

/** How the row says what it is showing, in the space a layer row has. */
export function summary({ sensor, window, first, last } = {}, sensors = []) {
  const name = sensors.find((entry) => entry.id === sensor)?.label ?? sensor ?? '';
  const short = name.replace(/\s*\(.*\)\s*$/, '');
  if (window !== DATED) {
    return [short, WINDOWS.find((entry) => entry.id === window)?.label].filter(Boolean).join(' · ');
  }
  const start = asDay(first);
  if (!start) return [short, 'pick a date'].filter(Boolean).join(' · ');
  const end = asDay(last);
  return [short, end && end !== start ? `${start} → ${end}` : start].filter(Boolean).join(' · ');
}

/**
 * What the Layers row says about the key, from `/api/firms/sensors`.
 *
 * `keyed` alone said "needs a free key" for three different things. Each now
 * has its own word and its own way out: no key, a key switched off in
 * Settings, and a key FIRMS said it does not know. A spent allowance is none
 * of these, and the layer stays on (`firmsNote`).
 */
const KEY_STATES = {
  missing: { detail: 'needs a free key', title: 'Add a NASA FIRMS key in Settings → Imagery', action: 'Add a FIRMS key' },
  off: { detail: 'off in Settings', title: 'Switched off in Settings → Imagery', action: 'Turn it on' },
  refused: { detail: 'key refused', title: 'FIRMS does not know this key. Test it in Settings → Imagery', action: 'Check the key' },
};

export function keyState({ keyed, state } = {}) {
  if (keyed) return { usable: true, detail: '', title: '', action: '' };
  return { usable: false, ...(KEY_STATES[state] ?? KEY_STATES.missing) };
}

/** A dated range longer than this spends the allowance in a few screens. */
export const LONG_RANGE_DAYS = 7;

function rangeDays({ first, last } = {}) {
  const start = asDay(first);
  if (!start) return 0;
  const end = asDay(last) || start;
  return Math.round((Date.parse(`${end}T00:00:00Z`) - Date.parse(`${start}T00:00:00Z`)) / 86_400_000) + 1;
}

/**
 * The one sentence the row carries under its controls, or ''.
 *
 * In order: the layer paused on a spent allowance, a dated question with no
 * date yet, a range long enough to spend the allowance, and what the two
 * colours of a window longer than a day mean.
 */
export function firmsNote(choice = {}, paused = null) {
  if (paused) return 'FIRMS allowance used up. It refills within ten minutes.';
  if (!askable(choice)) return choice.window === DATED ? 'Pick a date to draw the detections.' : '';
  if (choice.window === DATED) {
    return rangeDays(choice) > LONG_RANGE_DAYS ? 'A long range spends the FIRMS allowance in a few screens.' : '';
  }
  return choice.window === '24h' ? '' : 'Red: the last 24 hours. Amber: before them.';
}