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
10.5 KB
Raw Blame
import { describe, it, expect } from 'vitest';
import {
  monthKey,
  monthCount,
  tilesShort,
  tilesOfFree,
  freeTierShare,
  freeTier,
  usageBlocked,
  displayProviderId,
  providerStatus,
  layerCell,
  FREE_TIER,
  BLOCK_SHARE,
  ECO_MAX_ZOOM,
  USAGE_LINKS,
} from './usage.js';

describe('monthKey', () => {
  it('formats a UTC year-month bucket', () => {
    expect(monthKey(new Date(Date.UTC(2026, 6, 14)))).toBe('2026-07');
    expect(monthKey(new Date(Date.UTC(2026, 11, 31)))).toBe('2026-12');
  });
});

describe('monthCount', () => {
  const usage = { google: { '2026-07': 1234 }, mapbox: { '2026-07': 87 } };

  it('reads the month bucket for a meter', () => {
    expect(monthCount(usage, 'google', '2026-07')).toBe(1234);
  });

  it('is zero for unknown meters or empty usage', () => {
    expect(monthCount(usage, 'bing', '2026-07')).toBe(0);
    expect(monthCount(undefined, 'google', '2026-07')).toBe(0);
    expect(monthCount(usage, 'google', '2026-01')).toBe(0);
  });
});

describe('tilesShort', () => {
  it('is a compact map-pill readout', () => {
    expect(tilesShort(767)).toBe('767 tiles');
    expect(tilesShort(12430)).toBe('12,430 tiles');
    expect(tilesShort(1)).toBe('1 tile');
  });

  it('the Maps JS meter counts map loads, not tiles', () => {
    expect(tilesShort(3, 'google_js')).toBe('3 map loads');
    expect(tilesShort(1, 'google_js')).toBe('1 map load');
  });

  it('the Sentinel Hub meter counts requests — a tile is one, so is a date lookup', () => {
    expect(tilesShort(767, 'sentinelhub')).toBe('767 requests');
    expect(tilesShort(1, 'sentinelhub')).toBe('1 request');
  });
});

describe('tilesOfFree', () => {
  it('shows the count against the documented free allowance', () => {
    expect(tilesOfFree(767, 'mapbox')).toBe('767 / 200,000 free tiles');
    expect(tilesOfFree(12430, 'google')).toBe('12,430 / 100,000 free tiles');
    expect(tilesOfFree(42, 'google_js')).toBe('42 / 10,000 free map loads');
  });

  it('falls back to the plain count for meters without a known allowance', () => {
    expect(tilesOfFree(42, 'bing')).toBe('42 tiles');
  });
});

describe('freeTierShare', () => {
  it('is the fraction of the free allowance used', () => {
    expect(freeTierShare(100_000, 'mapbox')).toBe(0.5);
    expect(freeTierShare(150_000, 'google')).toBe(1.5); // over — UI can warn
    expect(freeTierShare(500, 'unknown')).toBe(0);
  });

  it('free tiers stay in sync with the label helper', () => {
    expect(FREE_TIER.mapbox).toBe(200_000);
    expect(FREE_TIER.google).toBe(100_000);
    // Copernicus documents 10k but provisions 30k to a General account
    // (observed 2026-07) — the default follows the account, not the doc
    expect(FREE_TIER.sentinelhub).toBe(30_000);
  });
});

describe("the account's own free tier", () => {
  // a free tier belongs to the account: providers grant more than they document
  // and change it silently, so the served figure always wins over our default
  const served = { sentinelhub: 50_000 };

  it('resolves to the served figure, falling back to the default', () => {
    expect(freeTier('sentinelhub', served)).toBe(50_000);
    expect(freeTier('mapbox', served)).toBe(200_000); // not overridden
    expect(freeTier('sentinelhub', null)).toBe(30_000);
    expect(freeTier('bing', served)).toBe(undefined);
  });

  it('moves the readout, the gauge and the block together', () => {
    expect(tilesOfFree(100, 'sentinelhub', served)).toBe('100 / 50,000 free requests');
    expect(freeTierShare(25_000, 'sentinelhub', served)).toBe(0.5);
    // 28k is past 90% of the shipped 30k default but nowhere near 90% of the
    // 50k this account really has: the correction is what keeps the block from
    // pausing a provider that is still well inside its allowance
    expect(usageBlocked(28_000, 'sentinelhub', {}, served)).toBe(false);
    expect(usageBlocked(28_000, 'sentinelhub', {}, null)).toBe(true);
    expect(usageBlocked(45_000, 'sentinelhub', {}, served)).toBe(true);
  });
});

describe('usageBlocked', () => {
  it('pauses a meter at the block share of its free tier', () => {
    expect(usageBlocked(FREE_TIER.google * BLOCK_SHARE, 'google')).toBe(true);
    expect(usageBlocked(FREE_TIER.google * BLOCK_SHARE - 1, 'google')).toBe(false);
  });

  it('the per-provider override lifts the pause', () => {
    expect(usageBlocked(FREE_TIER.mapbox, 'mapbox', { mapbox: true })).toBe(false);
    expect(usageBlocked(FREE_TIER.mapbox, 'mapbox', { google: true })).toBe(true);
  });

  it('unmetered providers never block', () => {
    expect(usageBlocked(10_000_000, 'bing')).toBe(false);
  });
});

describe('displayProviderId', () => {
  const google = { id: 'google-satellite', meter: 'google' };
  const esri = { id: 'esri-world-imagery', meter: null };

  it('keeps free providers as-is at any zoom', () => {
    expect(displayProviderId(esri, 3)).toBe('esri-world-imagery');
    expect(displayProviderId(esri, 19)).toBe('esri-world-imagery');
  });

  it('eco mode swaps billed basemaps for free imagery when zoomed out', () => {
    expect(displayProviderId(google, ECO_MAX_ZOOM)).toBe('esri-world-imagery');
    expect(displayProviderId(google, ECO_MAX_ZOOM + 1)).toBe('google-satellite');
    expect(displayProviderId(google, ECO_MAX_ZOOM, { eco: false })).toBe('google-satellite');
  });

  it('the eco threshold is configurable (default z15)', () => {
    expect(ECO_MAX_ZOOM).toBe(15);
    expect(displayProviderId(google, 17, { ecoMaxZoom: 17 })).toBe('esri-world-imagery');
    expect(displayProviderId(google, 15, { ecoMaxZoom: 12 })).toBe('google-satellite');
  });

  it('the Maps JS widget never eco-swaps (a swap re-bills a map load)', () => {
    const widget = { id: 'google-js', meter: 'google_js', widget: 'google-maps-js', eco_max_zoom: 0 };
    expect(displayProviderId(widget, 3)).toBe('google-js');
    expect(displayProviderId(widget, 15, { ecoMaxZoom: 21 })).toBe('google-js');
    // the soft block still protects the quota, eco or not
    expect(displayProviderId(widget, 18, { blocked: true })).toBe('esri-world-imagery');
  });

  it("a provider's own eco threshold wins over the global one", () => {
    // Sentinel-2 caps at z14, so the global z15 would hide it at every zoom it
    // can serve; its own z7 keeps everything from z8 in alive.
    const s2 = { id: 'sentinel2', meter: 'sentinelhub', eco_max_zoom: 7 };
    expect(displayProviderId(s2, 7)).toBe('esri-world-imagery');
    expect(displayProviderId(s2, 8)).toBe('sentinel2');
    expect(displayProviderId(s2, 14)).toBe('sentinel2');
    // the user's global setting doesn't drag it back under
    expect(displayProviderId(s2, 14, { ecoMaxZoom: 15 })).toBe('sentinel2');
    // and eco off still means off
    expect(displayProviderId(s2, 3, { eco: false })).toBe('sentinel2');
  });

  it('a paused meter always falls back, even zoomed in', () => {
    expect(displayProviderId(google, 19, { blocked: true })).toBe('esri-world-imagery');
  });

  it('handles the pre-load undefined provider', () => {
    expect(displayProviderId(undefined, 10)).toBe(undefined);
  });
});

describe('layerCell', () => {
  const google = { id: 'google-satellite', tile_size: 1024, oversample: 2 };
  const mapbox = { id: 'mapbox-satellite', tile_size: 512, oversample: 1 };
  const esri = { id: 'esri-world-imagery', tile_size: 256, oversample: 1 };

  it('shrinks the cell by the display oversample', () => {
    expect(layerCell(google, 16)).toBe(512); // 1024px tile shown 2× down = z+1 detail
    expect(layerCell(mapbox, 16)).toBe(512); // no oversample — native cell
    expect(layerCell(esri, 16)).toBe(256);
  });

  it('boosts only the z17 bracket for oversampled providers (soft z18 mosaic)', () => {
    expect(layerCell(google, 17)).toBe(256); // z19 detail for the z17 view
    expect(layerCell(google, 18)).toBe(512); // back to the cheap 2×
    expect(layerCell(mapbox, 17)).toBe(512); // non-oversampled providers unaffected
  });

  it('never goes below the 256px minimum cell', () => {
    expect(layerCell({ tile_size: 256, oversample: 2 }, 17)).toBe(256);
  });
});

describe('providerStatus', () => {
  const ok = { ok: true };
  const bad = { ok: false, detail: 'HTTP 403' };

  it('an unconfigured provider is idle, whatever else is true of it', () => {
    expect(providerStatus({ meter: 'mapbox' })).toEqual({ tone: 'idle', label: 'Not set' });
    // a stale verdict from a key that has since been cleared can't shout
    expect(providerStatus({ key: '  ', meter: 'mapbox', status: bad }).label).toBe('Not set');
  });

  it('reports a working key, and an untested one as untested', () => {
    expect(providerStatus({ key: 'pk.x', meter: 'mapbox', status: ok })).toEqual({
      tone: 'ok',
      label: 'Key works',
    });
    expect(providerStatus({ key: 'pk.x', meter: 'mapbox' })).toEqual({
      tone: 'idle',
      label: 'Untested',
    });
  });

  it('a failed key outranks every other state — it is why the basemap is benched', () => {
    expect(providerStatus({ key: 'pk.x', meter: 'mapbox', status: bad })).toEqual({
      tone: 'bad',
      label: 'Key failed',
    });
    // even switched off, and even at a quota that would otherwise pause it
    expect(providerStatus({ key: 'pk.x', meter: 'mapbox', status: bad, enabled: false }).label).toBe(
      'Key failed'
    );
    expect(
      providerStatus({ key: 'pk.x', meter: 'mapbox', status: bad, count: 199_000 }).label
    ).toBe('Key failed');
  });

  it('a disabled provider reads as off rather than as a quota state', () => {
    expect(
      providerStatus({ key: 'pk.x', meter: 'mapbox', status: ok, enabled: false, count: 199_000 })
    ).toEqual({ tone: 'idle', label: 'Off' });
  });

  it('separates the pause from a deliberate overrun', () => {
    const at90 = { key: 'pk.x', meter: 'mapbox', status: ok, count: 180_000 };
    expect(providerStatus(at90)).toEqual({ tone: 'bad', label: 'Paused' });
    expect(providerStatus({ ...at90, overrides: { mapbox: true } })).toEqual({
      tone: 'warn',
      label: 'Billing',
    });
  });

  it("measures against this account's corrected allowance, not the default", () => {
    const half = { key: 'x', meter: 'sentinelhub', status: ok, count: 9_500 };
    expect(providerStatus(half).label).toBe('Key works'); // 9.5k of the 30k default
    // the account Copernicus only documents 10k for: the same count is a pause
    expect(providerStatus({ ...half, tiers: { sentinelhub: 10_000 } }).label).toBe('Paused');
  });
});

describe('USAGE_LINKS', () => {
  it('points each billed meter at its provider dashboard', () => {
    expect(Object.keys(USAGE_LINKS).sort()).toEqual(Object.keys(FREE_TIER).sort());
    for (const url of Object.values(USAGE_LINKS)) expect(url).toMatch(/^https:\/\//);
  });
});