diff --git a/client/src/api/serviceIdentity.ts b/client/src/api/serviceIdentity.ts new file mode 100644 index 000000000..90fa0121d --- /dev/null +++ b/client/src/api/serviceIdentity.ts @@ -0,0 +1,8 @@ +import apiClient from './client'; + +/** /api/admin/service-identity: how this installation stands with the TREK services. Admin only. */ +export const serviceIdentityApi = { + status: (signal?: AbortSignal): Promise => + apiClient.get('/admin/service-identity', { signal }).then((r) => r.data), + regenerate: (): Promise => apiClient.post('/admin/service-identity/regenerate').then((r) => r.data), +}; diff --git a/client/src/components/Admin/ServiceIdentityPanel.test.tsx b/client/src/components/Admin/ServiceIdentityPanel.test.tsx new file mode 100644 index 000000000..3079a123e --- /dev/null +++ b/client/src/components/Admin/ServiceIdentityPanel.test.tsx @@ -0,0 +1,106 @@ +// FE-ADMIN-SVCID-001 to FE-ADMIN-SVCID-007 +import userEvent from '@testing-library/user-event'; +import type { ServiceIdentityStatus } from '@trek/shared'; +import { http, HttpResponse } from 'msw'; +import { describe, expect, it, vi } from 'vitest'; +import { server } from '../../../tests/helpers/msw/server'; +import { render, screen, waitFor } from '../../../tests/helpers/render'; +import ServiceIdentityPanel from './ServiceIdentityPanel'; + +// The keys themselves, so a test fails on a missing or renamed key rather than on wording. +vi.mock('../../i18n', async (importOriginal) => ({ + ...(await importOriginal()), + useTranslation: () => ({ t: (key: string) => key, locale: 'en-US' }), +})); + +const CONNECTED: ServiceIdentityStatus = { + state: 'connected', + tier: 'std', + keySource: 'registered', + quota: { limit: 10_000, used: 2_500, remaining: 7_500, resetAt: '2026-10-30T00:00:00.000Z' }, + lastSeenAt: '2026-10-29T12:00:00.000Z', +}; + +function serve(status: ServiceIdentityStatus) { + server.use(http.get('/api/admin/service-identity', () => HttpResponse.json(status))); +} + +describe('ServiceIdentityPanel', () => { + it('FE-ADMIN-SVCID-001: shows the state, the tier and today against the limit', async () => { + serve(CONNECTED); + render(); + expect(await screen.findByText('admin.trekApi.quota.state.connected')).toBeInTheDocument(); + expect(screen.getByText('admin.trekApi.quota.tier.std')).toBeInTheDocument(); + const bar = screen.getByRole('progressbar', { name: 'admin.trekApi.quota.title' }); + expect(bar).toHaveAttribute('aria-valuenow', '2500'); + expect(bar).toHaveAttribute('aria-valuemax', '10000'); + expect(screen.getByText('2,500 / 10,000')).toBeInTheDocument(); + expect(screen.getByText('7,500')).toBeInTheDocument(); + expect(screen.getByText('admin.trekApi.quota.resets')).toBeInTheDocument(); + expect(screen.queryByText(/admin\.trekApi\.quota\.hint\./)).toBeNull(); + }); + + it('FE-ADMIN-SVCID-002: an installation without a key says so and offers a new identity', async () => { + serve({ state: 'legacy', tier: 'legacy', keySource: null, quota: null, lastSeenAt: null }); + render(); + expect(await screen.findByText('admin.trekApi.quota.hint.legacy')).toBeInTheDocument(); + expect(screen.queryByRole('progressbar')).toBeNull(); + expect(screen.getByRole('button', { name: 'admin.trekApi.quota.regenerate' })).toBeInTheDocument(); + }); + + it('FE-ADMIN-SVCID-003: switched off, it shows why and offers nothing', async () => { + serve({ state: 'off', tier: null, keySource: null, quota: null, lastSeenAt: null }); + render(); + expect(await screen.findByText('admin.trekApi.quota.hint.off')).toBeInTheDocument(); + expect(screen.queryByRole('button', { name: 'admin.trekApi.quota.regenerate' })).toBeNull(); + }); + + it('FE-ADMIN-SVCID-004: a key from the environment is named, and only changed there', async () => { + serve({ ...CONNECTED, keySource: 'env', tier: 'own' }); + render(); + expect(await screen.findByText('admin.trekApi.quota.envKey')).toBeInTheDocument(); + expect(screen.queryByRole('button', { name: 'admin.trekApi.quota.regenerate' })).toBeNull(); + }); + + it('FE-ADMIN-SVCID-005: a connected key without an allowance to show says it cannot be read', async () => { + serve({ ...CONNECTED, quota: null }); + render(); + expect(await screen.findByText('admin.trekApi.quota.unavailable')).toBeInTheDocument(); + }); + + it('FE-ADMIN-SVCID-006: a failed read says so instead of showing nothing', async () => { + server.use(http.get('/api/admin/service-identity', () => HttpResponse.json({ error: 'nope' }, { status: 500 }))); + render(); + expect(await screen.findByText('admin.trekApi.quota.unavailable')).toBeInTheDocument(); + }); + + it('FE-ADMIN-SVCID-007: a revoked key asks before it starts over, then shows the new state', async () => { + let regenerated = 0; + serve({ state: 'revoked', tier: 'std', keySource: 'registered', quota: null, lastSeenAt: null }); + server.use( + http.post('/api/admin/service-identity/regenerate', () => { + regenerated += 1; + return HttpResponse.json({ + state: 'registering', + tier: 'legacy', + keySource: null, + quota: null, + lastSeenAt: null, + }); + }) + ); + const user = userEvent.setup(); + render(); + expect(await screen.findByText('admin.trekApi.quota.hint.revoked')).toBeInTheDocument(); + + await user.click(screen.getByRole('button', { name: 'admin.trekApi.quota.regenerate' })); + expect(screen.getByText('admin.trekApi.quota.regenerateBody')).toBeInTheDocument(); + expect(regenerated).toBe(0); + + const confirm = screen.getAllByRole('button', { name: 'admin.trekApi.quota.regenerate' }).at(-1); + if (!confirm) throw new Error('no confirm button'); + await user.click(confirm); + await waitFor(() => expect(regenerated).toBe(1)); + expect(await screen.findByText('admin.trekApi.quota.hint.registering')).toBeInTheDocument(); + }); +}); diff --git a/client/src/components/Admin/ServiceIdentityPanel.tsx b/client/src/components/Admin/ServiceIdentityPanel.tsx new file mode 100644 index 000000000..61dd36eb0 --- /dev/null +++ b/client/src/components/Admin/ServiceIdentityPanel.tsx @@ -0,0 +1,157 @@ +import type { ServiceIdentityState, ServiceIdentityStatus, ServiceQuotaView } from '@trek/shared'; +import { RefreshCw } from 'lucide-react'; +import { useRef, useState } from 'react'; +import { useTranslation } from '../../i18n'; +import { useSettingsStore } from '../../store/settingsStore'; +import type { TranslationFn } from '../../types'; +import { getApiErrorMessage } from '../../utils/apiError'; +import { formatClockTime } from '../../utils/formatters'; +import ConfirmDialog from '../shared/ConfirmDialog'; +import { useToast } from '../shared/Toast'; +import { useServiceIdentity } from './useServiceIdentity'; + +const STATE_DOT: Record = { + connected: 'bg-success', + registering: 'bg-warning motion-safe:animate-pulse', + legacy: 'bg-[var(--text-faint)]', + off: 'bg-[var(--text-faint)]', + revoked: 'bg-danger', +}; + +/** Below a tenth of the day left the bar turns amber, at nothing left red. */ +function barTone(quota: ServiceQuotaView): string { + if (quota.remaining === 0) return 'bg-danger'; + return quota.remaining < quota.limit / 10 ? 'bg-warning' : 'bg-accent'; +} + +function Stat({ label, value }: { label: string; value: string }) { + return ( +
+
{label}
+
{value}
+
+ ); +} + +function QuotaMeter({ quota }: { quota: ServiceQuotaView }) { + const { t, locale } = useTranslation(); + const is12h = useSettingsStore((s) => s.settings.time_format === '12h'); + const number = new Intl.NumberFormat(locale); + const share = quota.limit > 0 ? Math.min(100, (quota.used / quota.limit) * 100) : 100; + const reset = new Date(quota.resetAt); + const resetAt = formatClockTime( + `${String(reset.getHours()).padStart(2, '0')}:${String(reset.getMinutes()).padStart(2, '0')}`, + is12h + ); + + return ( +
+
+
+
+
+ + + +
+
+ ); +} + +function stateHint(t: TranslationFn, status: ServiceIdentityStatus | null, failed: boolean): string | null { + if (!status) return failed ? t('admin.trekApi.quota.unavailable') : null; + if (status.state !== 'connected') return t(`admin.trekApi.quota.hint.${status.state}`); + return status.quota ? null : t('admin.trekApi.quota.unavailable'); +} + +/** + * How this installation stands with the TREK services: whether it has its key, + * today's allowance against what is used, and when the count starts again. + * Read when the card is in view and refreshed every 30 seconds while it stays. + */ +export default function ServiceIdentityPanel() { + const { t } = useTranslation(); + const toast = useToast(); + const panel = useRef(null); + const { status, failed, regenerating, regenerate } = useServiceIdentity(panel); + const [confirming, setConfirming] = useState(false); + + const confirmRegenerate = async () => { + setConfirming(false); + try { + await regenerate(); + toast.success(t('admin.trekApi.quota.regenerated')); + } catch (err) { + toast.error(getApiErrorMessage(err, t('common.error'))); + } + }; + + const hint = stateHint(t, status, failed); + const canRegenerate = status !== null && status.keySource !== 'env' && status.state !== 'off'; + + return ( +
+
+

+

+ {status?.tier && ( + + {t(`admin.trekApi.quota.tier.${status.tier}`)} + + )} +
+ + {status?.quota && status.state !== 'off' && } + {hint &&

{hint}

} + + {status?.keySource === 'env' && ( +

{t('admin.trekApi.quota.envKey')}

+ )} + {canRegenerate && ( + + )} + + setConfirming(false)} + onConfirm={() => void confirmRegenerate()} + title={t('admin.trekApi.quota.regenerateTitle')} + message={t('admin.trekApi.quota.regenerateBody')} + confirmLabel={t('admin.trekApi.quota.regenerate')} + danger={false} + /> +
+ ); +} diff --git a/client/src/components/Admin/useServiceIdentity.test.ts b/client/src/components/Admin/useServiceIdentity.test.ts new file mode 100644 index 000000000..4fc165723 --- /dev/null +++ b/client/src/components/Admin/useServiceIdentity.test.ts @@ -0,0 +1,91 @@ +// FE-ADMIN-SVCID-HOOK-001 to FE-ADMIN-SVCID-HOOK-004 +import { act, renderHook } from '@testing-library/react'; +import type { ServiceIdentityStatus } from '@trek/shared'; +import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'; +import { useServiceIdentity } from './useServiceIdentity'; + +const { status, regenerate, visible } = vi.hoisted(() => ({ + status: vi.fn(), + regenerate: vi.fn(), + visible: { current: true }, +})); + +vi.mock('../../repo/serviceIdentityRepo', () => ({ serviceIdentityRepo: { status, regenerate } })); +vi.mock('../../hooks/useElementVisible', () => ({ useElementVisible: () => visible.current })); + +const LEGACY: ServiceIdentityStatus = { + state: 'legacy', + tier: 'legacy', + keySource: null, + quota: null, + lastSeenAt: null, +}; +const card = { current: null }; + +beforeEach(() => { + vi.useFakeTimers(); + visible.current = true; + status.mockReset().mockResolvedValue(LEGACY); + regenerate.mockReset(); +}); + +afterEach(() => vi.useRealTimers()); + +describe('useServiceIdentity', () => { + it('FE-ADMIN-SVCID-HOOK-001: reads once in view, then every 30 seconds', async () => { + const { result } = renderHook(() => useServiceIdentity(card)); + await act(async () => {}); + expect(result.current.status).toEqual(LEGACY); + expect(status).toHaveBeenCalledTimes(1); + await act(async () => { + await vi.advanceTimersByTimeAsync(30_000); + }); + expect(status).toHaveBeenCalledTimes(2); + }); + + it('FE-ADMIN-SVCID-HOOK-002: reads nothing while the card is out of view, and stops when it leaves', async () => { + visible.current = false; + const { rerender } = renderHook(() => useServiceIdentity(card)); + await act(async () => { + await vi.advanceTimersByTimeAsync(90_000); + }); + expect(status).not.toHaveBeenCalled(); + + visible.current = true; + rerender(); + await act(async () => {}); + expect(status).toHaveBeenCalledTimes(1); + + visible.current = false; + rerender(); + await act(async () => { + await vi.advanceTimersByTimeAsync(90_000); + }); + expect(status).toHaveBeenCalledTimes(1); + }); + + it('FE-ADMIN-SVCID-HOOK-003: marks a failed read, and clears the mark on the next good one', async () => { + status.mockRejectedValueOnce(new Error('offline')); + const { result } = renderHook(() => useServiceIdentity(card)); + await act(async () => {}); + expect(result.current.failed).toBe(true); + await act(async () => { + await vi.advanceTimersByTimeAsync(30_000); + }); + expect(result.current.failed).toBe(false); + }); + + it('FE-ADMIN-SVCID-HOOK-004: a new identity replaces the status, and a refusal reaches the caller', async () => { + const registering = { ...LEGACY, state: 'registering' as const }; + regenerate.mockResolvedValueOnce(registering).mockRejectedValueOnce(new Error('409')); + const { result } = renderHook(() => useServiceIdentity(card)); + await act(async () => { + await result.current.regenerate(); + }); + expect(result.current.status).toEqual(registering); + await act(async () => { + await expect(result.current.regenerate()).rejects.toThrow('409'); + }); + expect(result.current.regenerating).toBe(false); + }); +}); diff --git a/client/src/components/Admin/useServiceIdentity.ts b/client/src/components/Admin/useServiceIdentity.ts new file mode 100644 index 000000000..fd40133f8 --- /dev/null +++ b/client/src/components/Admin/useServiceIdentity.ts @@ -0,0 +1,51 @@ +import type { ServiceIdentityStatus } from '@trek/shared'; +import { useCallback, useEffect, useState, type RefObject } from 'react'; +import { useElementVisible } from '../../hooks/useElementVisible'; +import { serviceIdentityRepo } from '../../repo/serviceIdentityRepo'; + +const REFRESH_MS = 30_000; + +/** + * The installation's standing with the TREK services for the admin card: + * read when the card comes into view, then every 30 seconds while it stays + * there. Admin configuration, online only like the rest of the settings tab. + */ +export function useServiceIdentity(card: RefObject) { + const visible = useElementVisible(card); + const [status, setStatus] = useState(null); + const [failed, setFailed] = useState(false); + const [regenerating, setRegenerating] = useState(false); + + useEffect(() => { + if (!visible) return; + const controller = new AbortController(); + const refresh = () => { + serviceIdentityRepo.status(controller.signal).then( + (next) => { + setStatus(next); + setFailed(false); + }, + () => { + if (!controller.signal.aborted) setFailed(true); + } + ); + }; + refresh(); + const timer = setInterval(refresh, REFRESH_MS); + return () => { + controller.abort(); + clearInterval(timer); + }; + }, [visible]); + + const regenerate = useCallback(async (): Promise => { + setRegenerating(true); + try { + setStatus(await serviceIdentityRepo.regenerate()); + } finally { + setRegenerating(false); + } + }, []); + + return { status, failed, regenerating, regenerate }; +} diff --git a/client/src/hooks/useElementVisible.test.ts b/client/src/hooks/useElementVisible.test.ts new file mode 100644 index 000000000..9b9a74fba --- /dev/null +++ b/client/src/hooks/useElementVisible.test.ts @@ -0,0 +1,58 @@ +// FE-HOOK-VISIBLE-001 to FE-HOOK-VISIBLE-003 +import { act, renderHook } from '@testing-library/react'; +import { afterEach, describe, expect, it, vi } from 'vitest'; +import { useElementVisible } from './useElementVisible'; + +let report: ((entries: Array<{ isIntersecting: boolean }>) => void) | null = null; +const disconnect = vi.fn(); + +class FakeIntersectionObserver { + constructor(callback: (entries: Array<{ isIntersecting: boolean }>) => void) { + report = callback; + } + observe() {} + disconnect() { + disconnect(); + } +} + +function setVisibility(state: 'visible' | 'hidden') { + Object.defineProperty(document, 'visibilityState', { configurable: true, get: () => state }); + document.dispatchEvent(new Event('visibilitychange')); +} + +afterEach(() => { + vi.unstubAllGlobals(); + setVisibility('visible'); + report = null; +}); + +describe('useElementVisible', () => { + it('FE-HOOK-VISIBLE-001: follows the element in and out of view', () => { + vi.stubGlobal('IntersectionObserver', FakeIntersectionObserver); + const target = { current: document.createElement('div') }; + const { result, unmount } = renderHook(() => useElementVisible(target)); + act(() => report?.([{ isIntersecting: false }])); + expect(result.current).toBe(false); + act(() => report?.([{ isIntersecting: true }])); + expect(result.current).toBe(true); + unmount(); + expect(disconnect).toHaveBeenCalled(); + }); + + it('FE-HOOK-VISIBLE-002: counts as hidden while the tab is in the background', () => { + const target = { current: document.createElement('div') }; + const { result } = renderHook(() => useElementVisible(target)); + expect(result.current).toBe(true); + act(() => setVisibility('hidden')); + expect(result.current).toBe(false); + act(() => setVisibility('visible')); + expect(result.current).toBe(true); + }); + + it('FE-HOOK-VISIBLE-003: without IntersectionObserver the element counts as on screen', () => { + vi.stubGlobal('IntersectionObserver', undefined); + const { result } = renderHook(() => useElementVisible({ current: document.createElement('div') })); + expect(result.current).toBe(true); + }); +}); diff --git a/client/src/hooks/useElementVisible.ts b/client/src/hooks/useElementVisible.ts new file mode 100644 index 000000000..9f8dcf9a4 --- /dev/null +++ b/client/src/hooks/useElementVisible.ts @@ -0,0 +1,27 @@ +import { useEffect, useState, type RefObject } from 'react'; + +/** + * Whether an element is on screen and its tab in front. Without + * IntersectionObserver (an old browser, a test) the element counts as on + * screen, so whatever depends on it still runs. + */ +export function useElementVisible(target: RefObject): boolean { + const [onScreen, setOnScreen] = useState(true); + const [tabShown, setTabShown] = useState(() => document.visibilityState !== 'hidden'); + + useEffect(() => { + const element = target.current; + if (!element || typeof IntersectionObserver === 'undefined') return; + const observer = new IntersectionObserver(([entry]) => setOnScreen(entry?.isIntersecting ?? false)); + observer.observe(element); + return () => observer.disconnect(); + }, [target]); + + useEffect(() => { + const onChange = () => setTabShown(document.visibilityState !== 'hidden'); + document.addEventListener('visibilitychange', onChange); + return () => document.removeEventListener('visibilitychange', onChange); + }, []); + + return onScreen && tabShown; +} diff --git a/client/src/pages/admin/TrekApiCard.tsx b/client/src/pages/admin/TrekApiCard.tsx index 5722e2bac..52eecc23b 100644 --- a/client/src/pages/admin/TrekApiCard.tsx +++ b/client/src/pages/admin/TrekApiCard.tsx @@ -4,6 +4,7 @@ import TrekMark from '../../components/shared/TrekMark' import { fs } from '../../components/shared/DialogShell' import { StatusPill } from '../../components/Settings/settingsKit' import FoldSummary from './FoldSummary' +import ServiceIdentityPanel from '../../components/Admin/ServiceIdentityPanel' import type { TranslationFn } from '../../types' import { TREK_API_SOURCES as SOURCES, trekApiFacts, trekApiFields } from '../../components/Admin/trekApiModel' @@ -20,8 +21,9 @@ interface TrekApiCardProps { * to do and what made it shout over the settings it sat next to. * * Everything a reader can check is a measured number, not a claim: 73.6 million - * is the row count of the current index, and "no queries logged" is enforced in - * three places on the server rather than promised here. + * is the row count of the current index, "no queries logged" is enforced in + * three places on the server rather than promised here, and the allowance below + * the facts is what the service itself reports for this installation. */ const CHIP = 'rounded-full border px-2.5 py-[3px] font-medium' @@ -70,6 +72,8 @@ export default function TrekApiCard({ t }: TrekApiCardProps): React.ReactElement ))} + +
diff --git a/client/src/repo/serviceIdentityRepo.test.ts b/client/src/repo/serviceIdentityRepo.test.ts new file mode 100644 index 000000000..8d661aebc --- /dev/null +++ b/client/src/repo/serviceIdentityRepo.test.ts @@ -0,0 +1,41 @@ +// FE-SVCID-REPO-001 to FE-SVCID-REPO-003 +import type { ServiceIdentityStatus } from '@trek/shared'; +import { http, HttpResponse } from 'msw'; +import { afterEach, beforeEach, describe, expect, it } from 'vitest'; +import { server } from '../../tests/helpers/msw/server'; +import { _resetNetworkMode, setForcedOffline } from '../sync/networkMode'; +import { OnlineOnlyError } from './onlineOnly'; +import { serviceIdentityRepo } from './serviceIdentityRepo'; + +const STATUS: ServiceIdentityStatus = { + state: 'connected', + tier: 'std', + keySource: 'registered', + quota: { limit: 10_000, used: 1, remaining: 9_999, resetAt: '2026-10-30T00:00:00.000Z' }, + lastSeenAt: null, +}; + +beforeEach(() => _resetNetworkMode()); +afterEach(() => _resetNetworkMode()); + +describe('serviceIdentityRepo', () => { + it('FE-SVCID-REPO-001: reads and parses the status', async () => { + server.use(http.get('/api/admin/service-identity', () => HttpResponse.json(STATUS))); + await expect(serviceIdentityRepo.status()).resolves.toEqual(STATUS); + }); + + it('FE-SVCID-REPO-002: asks for a new identity and refuses an answer of another shape', async () => { + server.use( + http.post('/api/admin/service-identity/regenerate', () => HttpResponse.json({ ...STATUS, state: 'registering' })) + ); + await expect(serviceIdentityRepo.regenerate()).resolves.toMatchObject({ state: 'registering' }); + server.use(http.get('/api/admin/service-identity', () => HttpResponse.json({ state: 'gold' }))); + await expect(serviceIdentityRepo.status()).rejects.toThrow(); + }); + + it('FE-SVCID-REPO-003: asks nothing while offline', async () => { + setForcedOffline(true); + await expect(serviceIdentityRepo.status()).rejects.toBeInstanceOf(OnlineOnlyError); + await expect(serviceIdentityRepo.regenerate()).rejects.toBeInstanceOf(OnlineOnlyError); + }); +}); diff --git a/client/src/repo/serviceIdentityRepo.ts b/client/src/repo/serviceIdentityRepo.ts new file mode 100644 index 000000000..a4de67a06 --- /dev/null +++ b/client/src/repo/serviceIdentityRepo.ts @@ -0,0 +1,20 @@ +import { serviceIdentityStatusSchema, type ServiceIdentityStatus } from '@trek/shared'; +import { serviceIdentityApi } from '../api/serviceIdentity'; +import { requireOnline } from './onlineOnly'; + +/** + * The installation's identity towards the TREK services, as the admin card + * shows it. **Deliberately online-only, and no Dexie table:** it is live + * server state, and a cached copy would show an allowance that is long gone. + */ +export const serviceIdentityRepo = { + async status(signal?: AbortSignal): Promise { + requireOnline(); + return serviceIdentityStatusSchema.parse(await serviceIdentityApi.status(signal)); + }, + + async regenerate(): Promise { + requireOnline(); + return serviceIdentityStatusSchema.parse(await serviceIdentityApi.regenerate()); + }, +}; diff --git a/client/tests/helpers/msw/handlers/admin.ts b/client/tests/helpers/msw/handlers/admin.ts index 5251d393d..14b9aadf2 100644 --- a/client/tests/helpers/msw/handlers/admin.ts +++ b/client/tests/helpers/msw/handlers/admin.ts @@ -161,4 +161,9 @@ export const adminHandlers = [ http.get('/api/auth/validate-keys', () => { return HttpResponse.json({ maps: true, weather: true }); }), + + // The TREK API card's allowance panel, read whenever the settings tab renders it. + http.get('/api/admin/service-identity', () => { + return HttpResponse.json({ state: 'legacy', tier: 'legacy', keySource: null, quota: null, lastSeenAt: null }); + }), ];