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
7.7 KB
Raw Blame
/**
 * Keyed-provider usage bookkeeping (docs/IMAGERY_PROVIDERS.md).
 *
 * Billed providers (Mapbox, Google) get a per-month tile counter in
 * settings.json, maintained entirely by the backend: captures count the tiles
 * they stitch, and the live map's tiles flow through the backend proxy which
 * counts each one it serves. The frontend only reads the tally.
 */

/**
 * Default monthly free allowances, in billed requests — a yardstick for the
 * counter, not a guarantee (providers change their pricing; verify on their
 * pricing pages — links below). Verified 2026-07: Mapbox Static Tiles
 * 200k/month then $0.50 per extra 1,000 (billed to the account's card);
 * Google 2D Map Tiles 100k/month then $0.60 per extra 1,000, plus hard
 * server-side limits of 15,000 tiles/day and 6,000/min per project — a quota
 * cap set in the Cloud Console makes it stop instead of bill.
 * Sentinel Hub bills processing units, not tiles, but our 512×512 3-band 8-bit
 * tiles are 1 PU each, so the tile counter *is* the PU counter: 30,000 PU and
 * 30,000 requests/month on a free Copernicus General account (also 300/min).
 * google_js counts *map loads* (Maps JS dynamic maps — one per widget
 * instantiation, pan/zoom free): 10k/month on the 2025 Essentials tier.
 *
 * These are defaults only. A free tier belongs to the *account*, and providers
 * hand out more than they document without saying so (Copernicus still
 * documents 10k while provisioning 30k), so every function here takes the live
 * `free_tier` map from /api/settings — the user's own correction included — and
 * falls back to these. Mirror of config.FREE_TIER (which enforces the block).
 */
export const FREE_TIER = { mapbox: 200_000, google: 100_000, google_js: 10_000, sentinelhub: 30_000 };

/**
 * The imagery that costs nothing and needs no key.
 *
 * Named once because two different rules land on it: a billed basemap steps
 * aside for it when the month is nearly spent or the view is zoomed out
 * (`displayProviderId`), and any map that is only a reading shows it and
 * nothing else — the home page's, which has no basemap picker over it.
 */
export const FREE_IMAGERY = 'esri-world-imagery';

/** This account's allowance for a meter: the served figure, else the default. */
export function freeTier(meter, tiers = null) {
  return tiers?.[meter] ?? FREE_TIER[meter];
}

/** What one metered unit is, per meter — most bill tiles, the JS widget bills
 * whole map loads, and Sentinel Hub bills requests of any kind (a tile, but
 * also a date lookup). The wrong word would make the counter read as broken. */
export function meterUnit(meter) {
  if (meter === 'google_js') return 'map load';
  // Copernicus counts requests and PU against the same 30k allowance; a tile is
  // 1 of each, a WFS date query is 1 request and ~0.01 PU. "request" is the
  // word their own dashboard uses, and the only one true of both.
  if (meter === 'sentinelhub') return 'request';
  return 'tile';
}

/** Share of the free tier past which the backend pauses a provider. */
export const BLOCK_SHARE = 0.9;

/** Eco mode default: visual zoom at or below which free imagery replaces a
 * billed basemap. The live value is the user's `eco_max_zoom` setting. */
export const ECO_MAX_ZOOM = 15;

/** Sentinel's own eco default, mirrored from `engine/tiles.py`. */
export const SENTINEL_ECO_MAX_ZOOM = 7;

/** Where to watch the real counters and set caps, per provider. */
export const USAGE_LINKS = {
  mapbox: 'https://console.mapbox.com/account/statistics/',
  google: 'https://console.cloud.google.com/google/maps-apis/quotas',
  google_js: 'https://console.cloud.google.com/google/maps-apis/quotas',
  sentinelhub: 'https://shapps.dataspace.copernicus.eu/dashboard/#/account/usage',
};

/** True when a metered provider is paused: past the soft block, no override. */
export function usageBlocked(count, meter, overrides = {}, tiers = null) {
  const free = freeTier(meter, tiers);
  if (!free || overrides[meter]) return false;
  return count >= free * BLOCK_SHARE;
}

/**
 * The one-word verdict a collapsed provider card shows, so the whole Imagery
 * tab reads at a glance and only the card you open spends any text on itself.
 * Worst news first: a key that can't work is more urgent than a quota, and a
 * quota is more urgent than an untested key.
 */
export function providerStatus({
  key = '',
  enabled = true,
  status = null,
  count = 0,
  meter,
  overrides = {},
  tiers = null,
} = {}) {
  if (!key.trim()) return { tone: 'idle', label: 'Not set' };
  if (status && !status.ok) return { tone: 'bad', label: 'Key failed' };
  if (!enabled) return { tone: 'idle', label: 'Off' };
  if (usageBlocked(count, meter, overrides, tiers)) return { tone: 'bad', label: 'Paused' };
  // past the pause but explicitly overridden — the provider is billing now
  if (freeTierShare(count, meter, tiers) >= BLOCK_SHARE) return { tone: 'warn', label: 'Billing' };
  if (!status) return { tone: 'idle', label: 'Untested' };
  return { tone: 'ok', label: 'Key works' };
}

/**
 * CSS grid-cell size for a provider's live tile layer at a view zoom: the
 * tile edge shrunk by its display oversample. Oversampled providers (Google)
 * get one extra 2× boost for the z17 view only — the z18 mosaic it would
 * otherwise show is often an older/hazier collection than z19+ (the sharp
 * aerial; measured 2026-07), so that single bracket pays 4× for z19 detail
 * while every other zoom keeps the cheap 2×.
 */
export function layerCell(provider, zoom) {
  const boost = provider.oversample === 2 && zoom === 17 ? 2 : 1;
  return Math.max(256, provider.tile_size / ((provider.oversample || 1) * boost));
}

/**
 * The provider the live map should actually display. Billed basemaps step
 * aside for free imagery when paused (soft block) or zoomed out (eco mode —
 * paid detail only matters up close); captures follow the display, so
 * provenance stays honest.
 *
 * A provider's own `eco_max_zoom` wins over the user's global one, which is
 * tuned for basemaps that run to z22. Sentinel-2 stops at z14, so the global
 * z15 rule would swap it away at every zoom it can serve — it carries its own
 * shallower threshold instead. The soft block ignores all of this: it's a quota
 * guard, and a paused provider has nothing to show at any zoom.
 */
export function displayProviderId(
  provider,
  zoom,
  { eco = true, blocked = false, ecoMaxZoom = ECO_MAX_ZOOM } = {}
) {
  if (!provider?.meter) return provider?.id;
  if (blocked) return FREE_IMAGERY;
  const threshold = provider.eco_max_zoom ?? ecoMaxZoom;
  if (eco && zoom <= threshold) return FREE_IMAGERY;
  return provider.id;
}

/** The usage bucket for a moment in time: "YYYY-MM" (UTC, matches backend). */
export function monthKey(date = new Date()) {
  return `${date.getUTCFullYear()}-${String(date.getUTCMonth() + 1).padStart(2, '0')}`;
}

/** This month's tally for a meter out of the settings `usage` map. */
export function monthCount(usage, meter, month = monthKey()) {
  return Number(usage?.[meter]?.[month] ?? 0);
}

/** Compact readout for the map pill: "767 tiles" / "3 map loads". */
export function tilesShort(count, meter) {
  const unit = meterUnit(meter);
  return `${count.toLocaleString('en-US')} ${unit}${count === 1 ? '' : 's'}`;
}

/** Settings readout against the free allowance: "767 / 200,000 free tiles". */
export function tilesOfFree(count, meter, tiers = null) {
  const free = freeTier(meter, tiers);
  if (!free) return tilesShort(count, meter);
  return `${count.toLocaleString('en-US')} / ${free.toLocaleString('en-US')} free ${meterUnit(meter)}s`;
}

/** Share of the free allowance used this month, 0–1 (can exceed 1). */
export function freeTierShare(count, meter, tiers = null) {
  const free = freeTier(meter, tiers);
  return free ? count / free : 0;
}