Skip to content

A live bird collage card for your Home Assistant dashboard.

7.1 KB
Raw Blame
// Bird Card Proxy (#73): with the habird_proxy integration loaded, every
// BirdNET-Go call goes through HA's origin with HA's login - reads and
// audio via hass.fetchWithAuth, the live stream via a signed URL, review
// writes as a plain POST (the proxy does CSRF) - and nothing is fetched
// from BirdNET-Go directly. proxy: false restores the direct connection.
const path = require('path');
const ROOT = path.resolve(__dirname, '..');
const fs = require('fs');
const assert = require('assert');
const { JSDOM } = require('jsdom');
const CARD = fs.readFileSync(ROOT + '/dist/habird-card.js', 'utf8');

const summary = [
  { scientific_name: 'Corvus corax', common_name: 'Common Raven', count: 9, first_heard: '2026-06-01 09:00:00', last_heard: '2026-06-10 08:20:00', max_confidence: 0.95 },
];
const daily = summary.map(s => ({ ...s, hourly_counts: Array(24).fill(1), latest_heard: '08:20:00' }));
function answer(p, opts) {
  const json = (b) => ({ ok: true, status: 200, json: () => Promise.resolve(JSON.parse(JSON.stringify(b))),
    blob: () => Promise.resolve({ size: 3 }), arrayBuffer: () => Promise.resolve(new ArrayBuffer(8)), headers: { get: () => null } });
  if (p.startsWith('/api/v2/analytics/species/summary')) return json(summary);
  if (p.startsWith('/api/v2/analytics/species/daily')) return json(daily);
  if (p.includes('/analytics/')) return json({ data: [] });
  if (p.includes('/detections?queryType=search')) return json({ data: [
    { id: 42, date: '2026-06-10', time: '08:20:00', scientificName: 'Corvus corax', commonName: 'Common Raven', confidence: 0.95 },
  ], total: 1 });
  if (p.includes('/audio/')) return json({});
  if (p.endsWith('/review') && opts && opts.method === 'POST') return json({ ok: true });
  return { ok: false, status: 404, json: () => Promise.reject(404), headers: { get: () => null } };
}

function boot(config) {
  const dom = new JSDOM('<!doctype html><html><body></body></html>', {
    url: 'https://example.ui.nabu.casa/lovelace/birds', runScripts: 'outside-only', pretendToBeVisual: true,
  });
  const { window } = dom;
  const log = { direct: [], viaHa: [], signed: [], streams: [] };
  const errors = [];
  window.addEventListener('error', e => errors.push((e.error && e.error.stack) || e.message));
  window.fetch = (url, opts) => { log.direct.push(String(url)); return Promise.resolve(answer(String(url).replace(/^https?:\/\/[^/]+/, ''), opts)); };
  window.EventSource = class { constructor(u) { log.streams.push(u); } addEventListener() {} close() {} };
  window.URL.createObjectURL = () => 'blob:clip';
  window.Audio = class { addEventListener() {} load() {} play() { return Promise.resolve(); } pause() {} };
  Object.defineProperty(window.HTMLElement.prototype, 'clientWidth', { get() { return this.id === 'collage' ? 1200 : 300; } });
  Object.defineProperty(window.HTMLElement.prototype, 'clientHeight', { get() { return this.id === 'collage' ? 800 : 100; } });
  window.HTMLCanvasElement.prototype.getContext = () => null;
  window.ResizeObserver = class { observe() {} disconnect() {} };
  window.eval(CARD);
  const hass = {
    themes: { darkMode: false },
    states: {},
    user: { is_admin: true },
    config: { components: ['http', 'habird_proxy'] },
    fetchWithAuth: (url, opts) => {
      log.viaHa.push({ url, opts: opts || {} });
      assert.ok(url.startsWith('/api/habird_proxy/api/v2/'), 'proxy path: ' + url);
      return Promise.resolve(answer(url.replace('/api/habird_proxy', ''), opts));
    },
    callWS: (msg) => {
      if (msg.type === 'auth/sign_path') { log.signed.push(msg); return Promise.resolve({ path: msg.path + '?authSig=SIG' }); }
      return Promise.reject(new Error('unexpected ' + msg.type));
    },
  };
  const card = window.document.createElement('habird-card');
  card.setConfig(Object.assign({ api_token: 'bng-token-should-stay-server-side' }, config));
  card.hass = hass;
  window.document.body.appendChild(card);
  return { window, card, log, errors };
}

const click = (window, el) => el.dispatchEvent(new window.MouseEvent('click', { bubbles: true, composed: true }));

const A = boot({});
const B = boot({ proxy: false, birdnet_url: 'http://birdnet.lan:8080' });

setTimeout(() => {
  try {
    const { window, card, log } = A;
    const root = card.shadowRoot;
    assert.strictEqual(root.querySelectorAll('.gtile').length, 1, 'collage rendered from proxied data');
    assert.ok(log.viaHa.length >= 2, 'reads went through hass.fetchWithAuth: ' + log.viaHa.length);
    assert.deepStrictEqual(log.direct.filter(u => /\/api\/v2\//.test(u)), [], 'no direct BirdNET-Go fetches: ' + log.direct);
    assert.ok(log.viaHa.every(c => !JSON.stringify(c.opts.headers || {}).includes('bng-token')), 'api_token never sent from the browser');
    // Live stream: signed URL, then EventSource on it.
    assert.strictEqual(log.signed.length, 1, 'one sign_path request');
    assert.strictEqual(log.signed[0].path, '/api/habird_proxy/api/v2/detections/stream');
    assert.deepStrictEqual(log.streams, ['/api/habird_proxy/api/v2/detections/stream?authSig=SIG'], 'stream opened on the signed URL');
    // Play is enabled (the API is reachable) and fetches the clip through HA.
    const play = root.querySelector('.bird-card .chip.play');
    assert.ok(play && !play.disabled, 'play enabled through the proxy');
    click(window, play);
    setTimeout(() => {
      try {
        assert.ok(log.viaHa.some(c => c.url === '/api/habird_proxy/api/v2/audio/42'), 'clip fetched through HA: ' + log.viaHa.map(c => c.url));
        // Review write-back: plain POST through the proxy, no ingress, no CSRF from the browser.
        click(window, root.querySelector('.bird-card'));
        setTimeout(() => {
          try {
            const flag = root.querySelector('#modalRecordings .rec-row .flag');
            assert.ok(flag, 'flag rendered');
            click(window, flag); click(window, flag);
            setTimeout(() => {
              try {
                const post = log.viaHa.find(c => c.opts.method === 'POST');
                assert.ok(post, 'review POSTed');
                assert.strictEqual(post.url, '/api/habird_proxy/api/v2/detections/42/review');
                assert.strictEqual(JSON.parse(post.opts.body).verified, 'false_positive');
                assert.strictEqual(flag.getAttribute('data-state'), 'done', 'flag done: ' + flag.getAttribute('data-state'));
                // proxy: false -> talks to BirdNET-Go directly, as before.
                assert.strictEqual(B.log.viaHa.length, 0, 'proxy: false never uses the proxy');
                assert.ok(B.log.direct.some(u => u.startsWith('http://birdnet.lan:8080/api/v2/')), 'proxy: false fetches directly');
                assert.deepStrictEqual(A.errors.concat(B.errors), [], 'no page errors');
                console.log('PROXY TEST PASSED');
                process.exit(0);
              } catch (e) { console.error('FAIL:', e.message); process.exit(1); }
            }, 400);
          } catch (e) { console.error('FAIL:', e.message); process.exit(1); }
        }, 900);
      } catch (e) { console.error('FAIL:', e.message); process.exit(1); }
    }, 400);
  } catch (e) { console.error('FAIL:', e.message); process.exit(1); }
}, 1800);