@marinoscar/platform-web 0.0.0-stage → 0.1.0-next.4

package/dist/jobs/headless/use-jobs.js

@@ -0,0 +1,236 @@
+/**
+ * The job queue's list, its summary, and the five writes (issue #266, epic #254;
+ * moved into `@marinoscar/platform-web/jobs` by #854 from the reference app's
+ * `hooks/useJobs.ts`, behaviour unchanged).
+ *
+ * Three exports, one file, because they are three views of one surface and the
+ * page mounts all three together — the same reasoning `useMaintenance.ts` gives
+ * for holding two hooks that share no state. What they genuinely share is the
+ * contract: every function resolves rather than throws, and a failure is a
+ * STRING the page renders, because every caller is a click handler that needs
+ * to branch, not a place to handle an exception that has already been captured
+ * for display.
+ *
+ * =============================================================================
+ * `useVisiblePolling` — RE-EXPORTED, NOT DEFINED HERE
+ * =============================================================================
+ *
+ * The jobs page polls, because a queue is one of the two admin surfaces whose
+ * contents change with nobody touching it. The hook lives in
+ * `use-visible-polling.ts`, whose header keeps the full rationale — why the
+ * interval is torn down while the tab is hidden, and why returning to it
+ * fetches immediately rather than waiting out a period. The pages take it from
+ * the headless entry, which is what keeps a page test that mocks
+ * `@marinoscar/platform-web/jobs/headless` in control of the poll.
+ *
+ * Every hook takes an optional {@link JobsApi}; without one it uses the jobs
+ * adapters' client or `createJobsApi` over the platform host's transport.
+ */
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { isPlatformApiError } from '../../core/index.js';
+import { useIsMounted } from '../internal/use-is-mounted.js';
+import { useJobsApi } from './adapters.js';
+/**
+ * How often the jobs page re-asks, while its tab is in front.
+ *
+ * Ten seconds is chosen against what the data actually does: `GET /stats` is
+ * cached in-process for about two seconds, so a shorter poll would return the
+ * same cached numbers and buy only load, while a job that takes tens of seconds
+ * is not observed any better by asking three times as often.
+ *
+ * @stability experimental
+ */
+export const JOBS_POLL_INTERVAL_MS = 10_000;
+/** Turn any thrown value into the sentence the page will render. */
+function messageFor(err, fallback) {
+    if (isPlatformApiError(err)) {
+        // 403 is named explicitly because its remedy is a permission rather than a
+        // retry — the same treatment `useMaintenance` and `useEmailSettings` give it.
+        if (err.status === 403)
+            return 'You do not have permission to manage jobs';
+        return err.message;
+    }
+    return fallback;
+}
+/**
+ * The job list, `GET /api/admin/jobs`. Fetches nothing on mount: the caller
+ * runs `fetchJobs(params)` (filters, the activity window, the page, `orgId`)
+ * and `refresh` repeats the last query without raising the loading flag.
+ *
+ * @param api - a client to use instead of the adapters' or the host's.
+ * @returns the rows, the total, the state and the two fetchers.
+ *
+ * @example
+ * ```tsx
+ * const { jobs, total, fetchJobs } = useJobs();
+ * useEffect(() => { void fetchJobs({ orgId, status: 'failed', pageSize: 1 }); }, [fetchJobs, orgId]);
+ * ```
+ *
+ * @extensionPoint hook
+ * @stability experimental
+ */
+export function useJobs(api) {
+    const client = useJobsApi(api);
+    const [jobs, setJobs] = useState([]);
+    const [total, setTotal] = useState(0);
+    const [isLoading, setIsLoading] = useState(true);
+    const [error, setError] = useState(null);
+    // Every `setState` past an `await` is guarded: a request that settles after
+    // the component is gone must not schedule an update on it.
+    const isMounted = useIsMounted();
+    /**
+     * The last query, so a poll repeats the CURRENT view rather than an unfiltered
+     * one. A ref and not state: a re-render on every query would be a re-render
+     * that changes nothing on screen, and the value is only ever read from inside
+     * a callback.
+     */
+    const lastParams = useRef({});
+    const runQuery = useCallback(async (params, showLoading) => {
+        // A POLL DOES NOT RAISE THE LOADING FLAG. The rows stay on screen and the
+        // table keeps its scroll offset, its expansion and its focus; a spinner
+        // every ten seconds over data that is already correct is the fastest way
+        // to make a live table unusable.
+        if (showLoading)
+            setIsLoading(true);
+        setError(null);
+        try {
+            const response = await client.getJobs(params);
+            if (isMounted()) {
+                setJobs(response.items);
+                setTotal(response.total);
+            }
+        }
+        catch (err) {
+            if (isMounted()) {
+                setError(messageFor(err, 'Failed to load jobs'));
+                // Cleared, not left standing: rows from the previous successful query
+                // under an error banner read as the current state of the queue.
+                setJobs([]);
+                setTotal(0);
+            }
+        }
+        finally {
+            if (isMounted() && showLoading)
+                setIsLoading(false);
+        }
+    }, [client, isMounted]);
+    const fetchJobs = useCallback(async (params = {}) => {
+        lastParams.current = params;
+        await runQuery(params, true);
+    }, [runQuery]);
+    const refresh = useCallback(async () => {
+        await runQuery(lastParams.current, false);
+    }, [runQuery]);
+    return { jobs, total, isLoading, error, fetchJobs, refresh };
+}
+/**
+ * `GET /api/admin/jobs/stats`, on its own hook because it is on its own
+ * request: the strip above the table summarises the WHOLE queue, not the page
+ * of rows below it, so it neither takes the list's filters nor reloads when
+ * they change.
+ *
+ * @param api - a client to use instead of the adapters' or the host's.
+ * @returns the summary and its state.
+ *
+ * @extensionPoint hook
+ * @stability experimental
+ */
+export function useJobStats(api) {
+    const client = useJobsApi(api);
+    const [stats, setStats] = useState(null);
+    const [isLoading, setIsLoading] = useState(true);
+    const [error, setError] = useState(null);
+    const isMounted = useIsMounted();
+    const load = useCallback(async (showLoading) => {
+        if (showLoading)
+            setIsLoading(true);
+        try {
+            const data = await client.getJobStats();
+            if (isMounted()) {
+                setStats(data);
+                setError(null);
+            }
+        }
+        catch (err) {
+            // The PREVIOUS stats are kept on screen under the error, unlike the
+            // list above. A summary strip that empties on one failed poll makes a
+            // transient error look like a queue that just drained to zero.
+            if (isMounted())
+                setError(messageFor(err, 'Failed to load queue statistics'));
+        }
+        finally {
+            if (isMounted() && showLoading)
+                setIsLoading(false);
+        }
+    }, [client, isMounted]);
+    useEffect(() => {
+        void load(true);
+    }, [load]);
+    const refresh = useCallback(async () => {
+        await load(false);
+    }, [load]);
+    return { stats, isLoading, error, refresh };
+}
+/**
+ * The four writes, sharing one in-flight flag and one error.
+ *
+ * ONE FLAG FOR ALL FOUR is deliberate. They all mutate the same queue and the
+ * page re-reads it after any of them, so a second write started while the first
+ * is landing would be issued against counts that are already wrong — and its
+ * result would be reported over the top of the first one's. Disabling the whole
+ * action set for the duration is the honest reading of "these are not
+ * independent".
+ *
+ * @param onChanged - called after a write lands (the page re-reads the list and the summary).
+ * @param api - a client to use instead of the adapters' or the host's.
+ * @returns the four writes and their shared state.
+ *
+ * @extensionPoint hook
+ * @stability experimental
+ */
+export function useJobActions(onChanged, api) {
+    const client = useJobsApi(api);
+    const [isWorking, setIsWorking] = useState(false);
+    const [error, setError] = useState(null);
+    const isMounted = useIsMounted();
+    // Held in a ref for the same reason `useVisiblePolling` holds its callback:
+    // the page passes a fresh closure over the current filters on every render,
+    // and depending on it would rebuild all four callbacks each time.
+    const onChangedRef = useRef(onChanged);
+    onChangedRef.current = onChanged;
+    const run = useCallback(async (operation, fallback) => {
+        setIsWorking(true);
+        setError(null);
+        try {
+            const result = await operation();
+            // The queue changed, so whatever is on screen is now stale. Fired
+            // AFTER the write resolves and never in parallel with it: a refresh
+            // racing its own mutation is how a retried job flickers back to
+            // `failed` for one frame.
+            onChangedRef.current?.();
+            return result;
+        }
+        catch (err) {
+            if (isMounted())
+                setError(messageFor(err, fallback));
+            return null;
+        }
+        finally {
+            if (isMounted())
+                setIsWorking(false);
+        }
+    }, [isMounted]);
+    const retry = useCallback(async (id) => (await run(() => client.retryJob(id), 'Failed to retry job')) !== null, [run, client]);
+    const remove = useCallback(async (id) => (await run(async () => {
+        await client.deleteJob(id);
+        // `deleteJob` resolves `undefined` (the endpoint answers 204), and
+        // `run` reports failure as `null` — so a literal is returned to keep
+        // "succeeded" distinguishable from "failed".
+        return true;
+    }, 'Failed to delete job')) !== null, [run, client]);
+    const retryAllFailed = useCallback((type) => run(() => client.retryFailedJobs(type), 'Failed to retry failed jobs'), [run, client]);
+    const resetStuck = useCallback((olderThanMinutes) => run(() => client.resetStuckJobs(olderThanMinutes), 'Failed to reset stuck jobs'), [run, client]);
+    const clearError = useCallback(() => setError(null), []);
+    return { isWorking, error, clearError, retry, remove, retryAllFailed, resetStuck };
+}
+//# sourceMappingURL=use-jobs.js.map

package/dist/jobs/headless/use-jobs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-jobs.js","sourceRoot":"","sources":["../../../src/jobs/headless/use-jobs.ts"],"names":[],"mappings":"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"}

package/dist/jobs/headless/use-visible-polling.d.ts

@@ -0,0 +1,61 @@
+/**
+ * `useVisiblePolling` — an interval that stops with the tab.
+ *
+ * Introduced by issue #266 for the jobs page and EXTRACTED here by #271, when
+ * the worker-fleet page needed the same behaviour. Extracted rather than
+ * copied, and the distinction is the whole point of this file existing: two
+ * implementations of "poll, but not in a background tab" would be two places
+ * the `visibilitychange` teardown could be got subtly wrong, and the second
+ * one would be discovered the way the first would have been — by a dashboard
+ * left open overnight, months later, in somebody's database load graph.
+ *
+ * Moved into `@marinoscar/platform-web/jobs` by #854. The reference app keeps
+ * its own `hooks/useVisiblePolling.ts` for its backup, broadcast and About
+ * pages (other slices); the Jobs and Worker Nodes pages take this one from the
+ * headless entry, so a page test that mocks that entry still intercepts the
+ * poll.
+ *
+ * =============================================================================
+ * WHY THE INTERVAL STOPS WITH THE TAB
+ * =============================================================================
+ *
+ * These pages poll because their contents change with nobody touching them: a
+ * queue drains, a worker stops heartbeating. An operator watching either needs
+ * the numbers to move, and a manual refresh button turns "is it recovering"
+ * into a clicking exercise.
+ *
+ * A bare `setInterval` keeps firing in a background tab, and that is not a
+ * micro-optimisation to skip. A dashboard left open on a second monitor
+ * overnight is ~2,900 requests at a 10-second poll — each one a real query
+ * against the same database the workers are competing for — and every response
+ * is discarded, because nobody is looking. Browsers throttle background timers
+ * but do not stop them, and the throttling is neither uniform nor something a
+ * server capacity plan can rely on.
+ *
+ * So the interval is torn down on `visibilitychange` to hidden and rebuilt on
+ * the way back, with ONE IMMEDIATE FETCH on return. The immediate fetch is the
+ * half that makes the pause invisible to the operator: without it, a tab
+ * restored after an hour would show hour-old numbers for up to a full interval,
+ * which is worse than not pausing at all — stale data that looks live.
+ */
+/**
+ * Call `callback` every `intervalMs` — but only while the document is visible.
+ *
+ * `callback` is held in a ref rather than being an effect dependency: a page
+ * naturally passes a fresh closure on every render (it reads the current
+ * filters), and depending on it directly would tear down and rebuild the
+ * interval on every keystroke, so the timer would never actually reach its
+ * period. The ref is updated on each render, so a tick always calls the
+ * LATEST closure while the timer itself survives.
+ *
+ * `intervalMs <= 0` disables polling entirely, which is what a test — or a
+ * caller with no reason to poll — passes.
+ *
+ * @param callback - what each tick runs (the latest closure is always used).
+ * @param intervalMs - the period; `0` or less disables polling.
+ *
+ * @extensionPoint hook
+ * @stability experimental
+ */
+export declare function useVisiblePolling(callback: () => void, intervalMs: number): void;
+//# sourceMappingURL=use-visible-polling.d.ts.map

package/dist/jobs/headless/use-visible-polling.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-visible-polling.d.ts","sourceRoot":"","sources":["../../../src/jobs/headless/use-visible-polling.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAIH;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,IAAI,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI,CA4ChF"}

package/dist/jobs/headless/use-visible-polling.js

@@ -0,0 +1,102 @@
+/**
+ * `useVisiblePolling` — an interval that stops with the tab.
+ *
+ * Introduced by issue #266 for the jobs page and EXTRACTED here by #271, when
+ * the worker-fleet page needed the same behaviour. Extracted rather than
+ * copied, and the distinction is the whole point of this file existing: two
+ * implementations of "poll, but not in a background tab" would be two places
+ * the `visibilitychange` teardown could be got subtly wrong, and the second
+ * one would be discovered the way the first would have been — by a dashboard
+ * left open overnight, months later, in somebody's database load graph.
+ *
+ * Moved into `@marinoscar/platform-web/jobs` by #854. The reference app keeps
+ * its own `hooks/useVisiblePolling.ts` for its backup, broadcast and About
+ * pages (other slices); the Jobs and Worker Nodes pages take this one from the
+ * headless entry, so a page test that mocks that entry still intercepts the
+ * poll.
+ *
+ * =============================================================================
+ * WHY THE INTERVAL STOPS WITH THE TAB
+ * =============================================================================
+ *
+ * These pages poll because their contents change with nobody touching them: a
+ * queue drains, a worker stops heartbeating. An operator watching either needs
+ * the numbers to move, and a manual refresh button turns "is it recovering"
+ * into a clicking exercise.
+ *
+ * A bare `setInterval` keeps firing in a background tab, and that is not a
+ * micro-optimisation to skip. A dashboard left open on a second monitor
+ * overnight is ~2,900 requests at a 10-second poll — each one a real query
+ * against the same database the workers are competing for — and every response
+ * is discarded, because nobody is looking. Browsers throttle background timers
+ * but do not stop them, and the throttling is neither uniform nor something a
+ * server capacity plan can rely on.
+ *
+ * So the interval is torn down on `visibilitychange` to hidden and rebuilt on
+ * the way back, with ONE IMMEDIATE FETCH on return. The immediate fetch is the
+ * half that makes the pause invisible to the operator: without it, a tab
+ * restored after an hour would show hour-old numbers for up to a full interval,
+ * which is worse than not pausing at all — stale data that looks live.
+ */
+import { useEffect, useRef } from 'react';
+/**
+ * Call `callback` every `intervalMs` — but only while the document is visible.
+ *
+ * `callback` is held in a ref rather than being an effect dependency: a page
+ * naturally passes a fresh closure on every render (it reads the current
+ * filters), and depending on it directly would tear down and rebuild the
+ * interval on every keystroke, so the timer would never actually reach its
+ * period. The ref is updated on each render, so a tick always calls the
+ * LATEST closure while the timer itself survives.
+ *
+ * `intervalMs <= 0` disables polling entirely, which is what a test — or a
+ * caller with no reason to poll — passes.
+ *
+ * @param callback - what each tick runs (the latest closure is always used).
+ * @param intervalMs - the period; `0` or less disables polling.
+ *
+ * @extensionPoint hook
+ * @stability experimental
+ */
+export function useVisiblePolling(callback, intervalMs) {
+    const callbackRef = useRef(callback);
+    callbackRef.current = callback;
+    useEffect(() => {
+        if (intervalMs <= 0)
+            return;
+        let timer = null;
+        const stop = () => {
+            if (timer !== null) {
+                clearInterval(timer);
+                timer = null;
+            }
+        };
+        const start = () => {
+            // Guarded rather than assumed: `visibilitychange` can fire more than
+            // once for the same effective state, and an unguarded `setInterval`
+            // would leak a second timer and double the request rate.
+            if (timer !== null)
+                return;
+            timer = setInterval(() => callbackRef.current(), intervalMs);
+        };
+        const onVisibilityChange = () => {
+            if (document.hidden) {
+                stop();
+                return;
+            }
+            // Catch up FIRST, then resume — see the file header on why a resumed
+            // poll that waits out a full interval is worse than never pausing.
+            callbackRef.current();
+            start();
+        };
+        // A tab that is already hidden at mount never starts one.
+        if (!document.hidden)
+            start();
+        document.addEventListener('visibilitychange', onVisibilityChange);
+        return () => {
+            stop();
+            document.removeEventListener('visibilitychange', onVisibilityChange);
+        };
+    }, [intervalMs]);
+}
+//# sourceMappingURL=use-visible-polling.js.map

package/dist/jobs/headless/use-visible-polling.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-visible-polling.js","sourceRoot":"","sources":["../../../src/jobs/headless/use-visible-polling.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,OAAO,CAAC;AAE1C;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,iBAAiB,CAAC,QAAoB,EAAE,UAAkB;IACxE,MAAM,WAAW,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAC;IACrC,WAAW,CAAC,OAAO,GAAG,QAAQ,CAAC;IAE/B,SAAS,CAAC,GAAG,EAAE;QACb,IAAI,UAAU,IAAI,CAAC;YAAE,OAAO;QAE5B,IAAI,KAAK,GAA0C,IAAI,CAAC;QAExD,MAAM,IAAI,GAAG,GAAG,EAAE;YAChB,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;gBACnB,aAAa,CAAC,KAAK,CAAC,CAAC;gBACrB,KAAK,GAAG,IAAI,CAAC;YACf,CAAC;QACH,CAAC,CAAC;QAEF,MAAM,KAAK,GAAG,GAAG,EAAE;YACjB,qEAAqE;YACrE,oEAAoE;YACpE,yDAAyD;YACzD,IAAI,KAAK,KAAK,IAAI;gBAAE,OAAO;YAC3B,KAAK,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC,WAAW,CAAC,OAAO,EAAE,EAAE,UAAU,CAAC,CAAC;QAC/D,CAAC,CAAC;QAEF,MAAM,kBAAkB,GAAG,GAAG,EAAE;YAC9B,IAAI,QAAQ,CAAC,MAAM,EAAE,CAAC;gBACpB,IAAI,EAAE,CAAC;gBACP,OAAO;YACT,CAAC;YACD,qEAAqE;YACrE,mEAAmE;YACnE,WAAW,CAAC,OAAO,EAAE,CAAC;YACtB,KAAK,EAAE,CAAC;QACV,CAAC,CAAC;QAEF,0DAA0D;QAC1D,IAAI,CAAC,QAAQ,CAAC,MAAM;YAAE,KAAK,EAAE,CAAC;QAC9B,QAAQ,CAAC,gBAAgB,CAAC,kBAAkB,EAAE,kBAAkB,CAAC,CAAC;QAElE,OAAO,GAAG,EAAE;YACV,IAAI,EAAE,CAAC;YACP,QAAQ,CAAC,mBAAmB,CAAC,kBAAkB,EAAE,kBAAkB,CAAC,CAAC;QACvE,CAAC,CAAC;IACJ,CAAC,EAAE,CAAC,UAAU,CAAC,CAAC,CAAC;AACnB,CAAC"}

package/dist/jobs/internal/use-is-mounted.d.ts

@@ -0,0 +1,9 @@
+/**
+ * A stable getter for "is this component still mounted?", to guard `setState`
+ * in the tail of an async operation. A ref rather than state, and a getter
+ * rather than the ref, so callers can list it in a `useCallback` dependency
+ * array without invalidating on every render. Copied from the reference app's
+ * `hooks/useIsMounted.ts` (a slice-private helper, not exported).
+ */
+export declare function useIsMounted(): () => boolean;
+//# sourceMappingURL=use-is-mounted.d.ts.map

package/dist/jobs/internal/use-is-mounted.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-is-mounted.d.ts","sourceRoot":"","sources":["../../../src/jobs/internal/use-is-mounted.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,wBAAgB,YAAY,IAAI,MAAM,OAAO,CAW5C"}

package/dist/jobs/internal/use-is-mounted.js

@@ -0,0 +1,19 @@
+import { useCallback, useEffect, useRef } from 'react';
+/**
+ * A stable getter for "is this component still mounted?", to guard `setState`
+ * in the tail of an async operation. A ref rather than state, and a getter
+ * rather than the ref, so callers can list it in a `useCallback` dependency
+ * array without invalidating on every render. Copied from the reference app's
+ * `hooks/useIsMounted.ts` (a slice-private helper, not exported).
+ */
+export function useIsMounted() {
+    const mounted = useRef(true);
+    useEffect(() => {
+        mounted.current = true;
+        return () => {
+            mounted.current = false;
+        };
+    }, []);
+    return useCallback(() => mounted.current, []);
+}
+//# sourceMappingURL=use-is-mounted.js.map

package/dist/jobs/internal/use-is-mounted.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-is-mounted.js","sourceRoot":"","sources":["../../../src/jobs/internal/use-is-mounted.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,OAAO,CAAC;AAEvD;;;;;;GAMG;AACH,MAAM,UAAU,YAAY;IAC1B,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC;IAE7B,SAAS,CAAC,GAAG,EAAE;QACb,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC;QACvB,OAAO,GAAG,EAAE;YACV,OAAO,CAAC,OAAO,GAAG,KAAK,CAAC;QAC1B,CAAC,CAAC;IACJ,CAAC,EAAE,EAAE,CAAC,CAAC;IAEP,OAAO,WAAW,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;AAChD,CAAC"}

package/dist/jobs/ui/JobInsightsPage.d.ts

@@ -0,0 +1,178 @@
+/**
+ * Admin → Operations → Job Insights (`/admin/settings/jobs/insights`).
+ *
+ * Issue #266, epic #254; moved into `@marinoscar/platform-web/jobs` by #854
+ * from the reference app's `pages/Admin/JobInsightsPage.tsx`, same DOM and
+ * styles. The second of the two Jobs pages, and a REGISTRY CARD
+ * of its own rather than a tab on the first — `CLAUDE.md`'s Settings UI Pattern
+ * rule 2, applied to a case that genuinely tempts the other way. Jobs and Job
+ * Insights are not two views of one question: one is the queue's ROWS, which an
+ * operator acts on row by row, and the other is its BEHAVIOUR over a window,
+ * which nobody acts on at all. They are also two endpoints with two costs (a
+ * cached paginated read versus percentiles over a window), and a tab strip would
+ * make the expensive one load every time somebody opened the cheap one.
+ *
+ * Its route NESTS under the Jobs card's (`/admin/settings/jobs/insights`), which
+ * is the case `settingsPageTitle`'s longest-prefix rule exists for: a bare
+ * `startsWith` would let the `Jobs` card claim this path and the AppBar would
+ * title this page "Jobs".
+ *
+ * =============================================================================
+ * AN ESTIMATE MUST SAY HOW MUCH OF IT IS REAL
+ * =============================================================================
+ *
+ * Every ETA the API returns is `remaining x avgMs / concurrency`, but that
+ * `avgMs` comes from one of three places, and the response says which in
+ * `basis`:
+ *
+ *   `live`    — this type's own completed jobs. The estimate is MEASUREMENT.
+ *   `partial` — the average across every other type, because this one has no
+ *               history yet. The estimate is an ANALOGY, and a bad one whenever
+ *               job types differ in cost (they always do).
+ *   `none`    — nothing has succeeded in the window at all, so the number is a
+ *               shipped constant. The estimate is a PLACEHOLDER.
+ *
+ * So this page never renders those three the same way, and a `none` basis
+ * RENDERS NO DURATION AT ALL — not the number greyed out, not the number with
+ * an asterisk. A duration on screen is read as a measurement by everyone who
+ * has ever seen a progress bar, and "4 minutes" derived from a constant is a
+ * number that will be quoted to somebody else within the hour. The honest
+ * output for `none` is "No estimate yet", and the count of outstanding jobs
+ * beside it is the real information that case has.
+ *
+ * `partial` keeps its duration, hedged in words ("based on other job types"),
+ * because an analogy is still evidence — it is right about the order of
+ * magnitude in a way a constant is not.
+ *
+ * =============================================================================
+ * WHY IT DOES NOT POLL
+ * =============================================================================
+ *
+ * The sibling Jobs page polls every ten seconds; this one does not, and the
+ * asymmetry is deliberate. Nothing here moves at that timescale — a p95 over
+ * seven days does not change in ten seconds — so an interval would buy an
+ * expensive query per tick and no new information. `generatedAt` is on screen
+ * instead, so the operator can see how old the numbers are rather than assume
+ * they are live, and refreshing is an explicit act.
+ */
+import type { ReactElement } from 'react';
+import type { PageSlot, PageSlotsBase, TableSlots } from '../../core/index.js';
+import type { JobInsights, JobsTableColumn } from '../headless/index.js';
+import type { JobsPageHeaderProps } from './PageHeader.js';
+/** Persistence key for `user_settings.dataTables`. Never derived from the route. */
+export declare const TYPES_TABLE_ID = "admin-job-insights-types";
+/**
+ * What the Job Insights page passes its `Filters` slot.
+ *
+ * @stability experimental
+ */
+export interface JobInsightsFiltersSlotProps {
+    /** The history window in days that the numbers below cover. */
+    windowDays: number;
+    /** Selects another window (the API clamps it) and re-reads the analytics. */
+    onWindowDaysChange: (days: number) => void;
+}
+/**
+ * The slots of {@link JobInsightsPage}: the page-slot contract over a per-type
+ * row, and `Filters`.
+ *
+ * `Header` keeps the props it always had and gains `actions` (`null`).
+ * `Filters` is drawn beside the window selector, `Toolbar` above the per-type
+ * table, and `Columns` / `RowActions` / `DetailPanel` act on that table. The
+ * slots other than `Header` appear once the analytics have loaded; until then
+ * the page shows its spinner.
+ *
+ * @extensionPoint slot
+ * @stability experimental
+ */
+export interface JobInsightsPageSlots extends PageSlotsBase, TableSlots<JobTypeInsightRow, JobsTableColumn<JobTypeInsightRow>> {
+    /** Replaces the title and subtitle block. */
+    Header?: PageSlot<JobsPageHeaderProps>;
+    /** Extra controls beside the window selector. */
+    Filters?: PageSlot<JobInsightsFiltersSlotProps>;
+}
+/**
+ * The props of {@link JobInsightsPage}. Every prop is optional; the app's
+ * route renders `<JobInsightsPage />` as is.
+ *
+ * @extensionPoint slot
+ * @stability experimental
+ */
+export interface JobInsightsPageProps {
+    /** Where a viewer without `jobs:read` is sent. Default `'/'`. */
+    fallbackPath?: string;
+    /** Replaceable and additional parts of the page. */
+    slots?: JobInsightsPageSlots;
+}
+/**
+ * One per-type row of the Job Insights table: the window's distribution merged
+ * with the all-time totals. The row type of the page's table slots.
+ *
+ * @stability experimental
+ */
+export interface JobTypeInsightRow {
+    /** The job type's machine key. */
+    type: string;
+    /** The job type's display label. */
+    label: string;
+    /** Runs completed in the window (the denominator of the window's figures). */
+    samples: number;
+    /** Mean duration in the window in milliseconds, or `null` with no samples. */
+    avgMs: number | null;
+    /** Median duration in the window in milliseconds, or `null` with no samples. */
+    p50Ms: number | null;
+    /** 95th-percentile duration in the window in milliseconds, or `null` with no samples. */
+    p95Ms: number | null;
+    /** Completions per minute over the last hour. */
+    throughputPerMin: number;
+    /** All-time succeeded runs. */
+    lifetimeSucceeded: number;
+    /** All-time failed runs. */
+    lifetimeFailed: number;
+    /** All-time runs. */
+    lifetimeTotal: number;
+    /** All-time mean duration in milliseconds, or `null`. */
+    lifetimeAvgMs: number | null;
+    /** Runs the all-time mean is taken over. */
+    lifetimeSamples: number;
+}
+/**
+ * Merge `history.byType` (a distribution over the window) with `lifetime` (all-
+ * time totals) into ONE row per type.
+ *
+ * They are two blocks in the response because they answer different questions
+ * and the API refuses to pretend otherwise — `lifetime` has no percentiles,
+ * because percentiles cannot be reconstructed from purged rows. They are one
+ * TABLE here because the operator's question is per type ("what does this job
+ * type cost"), and reading it off two tables side by side means matching type
+ * names by eye. The lifetime columns are `detail` priority, so the window's
+ * numbers are what a narrow screen shows first.
+ *
+ * A type present in only one block still gets a row: a type that has run
+ * historically but not in the window has no percentiles (nulls, which render
+ * as an em dash), and a type new in this window has no lifetime rollup yet.
+ * Dropping either would silently hide a job type from a page whose whole
+ * purpose is per-type comparison.
+ */
+export declare function buildTypeInsightRows(insights: JobInsights): JobTypeInsightRow[];
+/**
+ * Admin → Operations → Job Insights: queue analytics over a window (duration
+ * percentiles, throughput, the ETA per type with its basis) and the all-time
+ * totals, with the `jobs:write` reset of the lifetime rollup. Gated on
+ * `jobs:read`. Does not poll.
+ *
+ * @param props - see {@link JobInsightsPageProps}.
+ * @returns the page.
+ *
+ * @example
+ * ```tsx
+ * <Route path="/admin/settings/jobs/insights" element={
+ *   <RequirePermission permission="jobs:read" fallback={<Navigate to="/" replace />}><JobInsightsPage /></RequirePermission>
+ * } />
+ * ```
+ *
+ * @extensionPoint component
+ * @stability experimental
+ */
+export declare function JobInsightsPage(props?: JobInsightsPageProps): ReactElement;
+//# sourceMappingURL=JobInsightsPage.d.ts.map

package/dist/jobs/ui/JobInsightsPage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"JobInsightsPage.d.ts","sourceRoot":"","sources":["../../../src/jobs/ui/JobInsightsPage.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,OAAO,CAAC;AAwB1C,OAAO,KAAK,EAAE,QAAQ,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAQ/E,OAAO,KAAK,EAAuB,WAAW,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAG9F,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAM3D,oFAAoF;AACpF,eAAO,MAAM,cAAc,6BAA6B,CAAC;AAEzD;;;;GAIG;AACH,MAAM,WAAW,2BAA2B;IAC1C,+DAA+D;IAC/D,UAAU,EAAE,MAAM,CAAC;IACnB,6EAA6E;IAC7E,kBAAkB,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAC5C;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,oBACf,SAAQ,aAAa,EACnB,UAAU,CAAC,iBAAiB,EAAE,eAAe,CAAC,iBAAiB,CAAC,CAAC;IACnE,6CAA6C;IAC7C,MAAM,CAAC,EAAE,QAAQ,CAAC,mBAAmB,CAAC,CAAC;IACvC,iDAAiD;IACjD,OAAO,CAAC,EAAE,QAAQ,CAAC,2BAA2B,CAAC,CAAC;CACjD;AAED;;;;;;GAMG;AACH,MAAM,WAAW,oBAAoB;IACnC,iEAAiE;IACjE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,oDAAoD;IACpD,KAAK,CAAC,EAAE,oBAAoB,CAAC;CAC9B;AA8BD;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,kCAAkC;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,oCAAoC;IACpC,KAAK,EAAE,MAAM,CAAC;IACd,8EAA8E;IAC9E,OAAO,EAAE,MAAM,CAAC;IAChB,8EAA8E;IAC9E,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,gFAAgF;IAChF,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,yFAAyF;IACzF,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,iDAAiD;IACjD,gBAAgB,EAAE,MAAM,CAAC;IACzB,+BAA+B;IAC/B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,4BAA4B;IAC5B,cAAc,EAAE,MAAM,CAAC;IACvB,qBAAqB;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,yDAAyD;IACzD,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,4CAA4C;IAC5C,eAAe,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,WAAW,GAAG,iBAAiB,EAAE,CAgD/E;AAoKD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,eAAe,CAAC,KAAK,GAAE,oBAAyB,GAAG,YAAY,CAyQ9E"}