@purposeinplay/payload-ai-translate 0.1.0

package/dist/views/BulkRunsHub/useBulkRunsList.js

@@ -0,0 +1,204 @@
+'use client';
+/**
+ * Polling hook for the bulk-translate runs list endpoint.
+ *
+ * Mirrors the structure of `useBulkTranslateActive` — 5s visibility-aware
+ * poll loop, offline threshold, refetch escape hatch.
+ *
+ * Polling is active only when:
+ *   1. `document.visibilityState === 'visible'`
+ *   2. Any batch in `data.batches` is in an active status.
+ *
+ * When those conditions are false the poll is suspended. The hook still
+ * fires once on mount and once when visibility returns.
+ */ import { useCallback, useEffect, useRef, useState } from 'react';
+import { readResponseError } from '../shared/fetch-error-body.js';
+import { isActiveStatus } from '../TranslationHub/BulkTranslate.types.js';
+const POLL_INTERVAL_MS = 5000;
+const OFFLINE_THRESHOLD = 3;
+const DEFAULT_LIMIT = 20;
+function buildUrl(basePath, filters, cursor = null, limit = DEFAULT_LIMIT) {
+    const params = new URLSearchParams();
+    if (filters.status) params.set('status', filters.status);
+    if (filters.mode) params.set('mode', filters.mode);
+    if (filters.triggeredBy) params.set('triggeredBy', filters.triggeredBy);
+    if (filters.since) params.set('since', filters.since);
+    if (filters.until) params.set('until', filters.until);
+    if (filters.hasFailures) params.set('hasFailures', 'true');
+    if (cursor) params.set('cursor', cursor);
+    params.set('limit', String(limit));
+    // Payload's collection-list router intercepts requests whose only query
+    // string is `?limit=N`, redirecting to a locale-prefixed canonical URL
+    // and 404ing on our custom endpoint. Adding a second param sidesteps
+    // the heuristic. `depth=0` is a no-op for our handler.
+    params.set('depth', '0');
+    const qs = params.toString();
+    return `${basePath}/api/translation-hub/bulk-translate${qs ? `?${qs}` : ''}`;
+}
+export function useBulkRunsList(basePath, filters) {
+    const [data, setData] = useState(null);
+    const [loading, setLoading] = useState(true);
+    const [error, setError] = useState(null);
+    const [failedStreak, setFailedStreak] = useState(0);
+    const [loadingMore, setLoadingMore] = useState(false);
+    const cancelledRef = useRef(false);
+    const timerRef = useRef(undefined);
+    // Stable ref so refetch() can be called from event handlers without
+    // re-subscribing to the effect.
+    const refetchRef = useRef(()=>undefined);
+    useEffect(()=>{
+        cancelledRef.current = false;
+        let isFirstFetch = true;
+        async function fetchOnce() {
+            const url = buildUrl(basePath, filters);
+            try {
+                const res = await fetch(url, {
+                    credentials: 'include'
+                });
+                if (cancelledRef.current) return;
+                if (res.status === 404) {
+                    setData({
+                        batches: [],
+                        nextCursor: null,
+                        total: 0
+                    });
+                    setError(null);
+                    setFailedStreak(0);
+                    return;
+                }
+                if (!res.ok) throw new Error(await readResponseError(res));
+                const json = await res.json();
+                if (cancelledRef.current) return;
+                // v1.2.5: same fix as BatchRow's polling — preserve
+                // load-more-appended batches across polling ticks. Pre-1.2.5
+                // the polling tick called setData(json) which fully replaced
+                // the batches array; if the user had clicked "Load more" to
+                // load page 2, the next polling tick wiped page 2 (the
+                // polling fetch returns only the first page). Now we merge:
+                // new batches override matching ids, prev batches not in the
+                // new response (i.e. loaded-more pages) survive. First fetch
+                // (filter change / mount) still replaces fully.
+                if (isFirstFetch) {
+                    setData(json);
+                    isFirstFetch = false;
+                } else {
+                    setData((prev)=>{
+                        if (!prev) return json;
+                        const newById = new Map(json.batches.map((b)=>[
+                                String(b.id),
+                                b
+                            ]));
+                        const preserved = prev.batches.filter((b)=>!newById.has(String(b.id)));
+                        return {
+                            ...json,
+                            batches: [
+                                ...json.batches,
+                                ...preserved
+                            ]
+                        };
+                    });
+                }
+                setError(null);
+                setFailedStreak(0);
+            } catch (e) {
+                if (cancelledRef.current) return;
+                setError(e instanceof Error ? e.message : String(e));
+                setFailedStreak((n)=>n + 1);
+            } finally{
+                if (!cancelledRef.current) {
+                    setLoading(false);
+                    // Only keep polling when page is visible AND a batch is active.
+                    if (document.visibilityState === 'visible') {
+                        // We can't read `data` here (stale closure) so we schedule
+                        // unconditionally; the interval handler checks activity itself.
+                        timerRef.current = setTimeout(maybePoll, POLL_INTERVAL_MS);
+                    }
+                }
+            }
+        }
+        function maybePoll() {
+            if (cancelledRef.current) return;
+            // Read latest data from the outer state via the ref we refresh below.
+            // If none of the current batches are active, suspend polling.
+            const shouldPoll = dataRef.current?.batches.some((b)=>isActiveStatus(b.status));
+            if (shouldPoll) {
+                fetchOnce();
+            } else {
+                // Reschedule — a new run might start while the tab is open.
+                timerRef.current = setTimeout(maybePoll, POLL_INTERVAL_MS);
+            }
+        }
+        function onVisibility() {
+            if (document.visibilityState === 'visible' && !cancelledRef.current) {
+                if (timerRef.current) clearTimeout(timerRef.current);
+                fetchOnce();
+            }
+        }
+        refetchRef.current = ()=>{
+            if (timerRef.current) clearTimeout(timerRef.current);
+            fetchOnce();
+        };
+        document.addEventListener('visibilitychange', onVisibility);
+        fetchOnce();
+        return ()=>{
+            cancelledRef.current = true;
+            if (timerRef.current) clearTimeout(timerRef.current);
+            document.removeEventListener('visibilitychange', onVisibility);
+        };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [
+        basePath,
+        filters.status,
+        filters.mode,
+        filters.triggeredBy,
+        filters.since,
+        filters.until,
+        filters.hasFailures
+    ]);
+    // Keep a ref to latest data so `maybePoll` doesn't stale-close.
+    const dataRef = useRef(data);
+    useEffect(()=>{
+        dataRef.current = data;
+    }, [
+        data
+    ]);
+    const loadMore = useCallback(async ()=>{
+        const cursor = dataRef.current?.nextCursor;
+        if (!cursor || loadingMore) return;
+        setLoadingMore(true);
+        try {
+            const url = buildUrl(basePath, filters, cursor);
+            const res = await fetch(url, {
+                credentials: 'include'
+            });
+            if (!res.ok) throw new Error(await readResponseError(res));
+            const json = await res.json();
+            setData((prev)=>prev ? {
+                    ...json,
+                    batches: [
+                        ...prev.batches,
+                        ...json.batches
+                    ]
+                } : json);
+        } catch  {
+        // Non-fatal — the Load more button just stays visible.
+        } finally{
+            setLoadingMore(false);
+        }
+    }, [
+        basePath,
+        filters,
+        loadingMore
+    ]);
+    return {
+        data,
+        loading,
+        error,
+        isOffline: failedStreak >= OFFLINE_THRESHOLD,
+        refetch: ()=>refetchRef.current(),
+        loadMore,
+        loadingMore
+    };
+}
+export const BULK_RUNS_OFFLINE_THRESHOLD = OFFLINE_THRESHOLD;
+export const BULK_RUNS_POLL_INTERVAL_MS = POLL_INTERVAL_MS;

package/dist/views/BulkRunsHub/useUrlFilters.d.ts

@@ -0,0 +1,10 @@
+import type { BulkRunsFilterState, BulkRunsTimeRange } from '../TranslationHub/BulkTranslate.types.js';
+export { DEFAULT_FILTERS } from './urlFilters.js';
+export type UrlFiltersResult = {
+    filters: BulkRunsFilterState;
+    timeRange: BulkRunsTimeRange;
+    setFilters: (patch: Partial<BulkRunsFilterState>) => void;
+    setTimeRange: (range: BulkRunsTimeRange) => void;
+    clearAll: () => void;
+};
+export declare function useUrlFilters(): UrlFiltersResult;

package/dist/views/BulkRunsHub/useUrlFilters.js

@@ -0,0 +1,88 @@
+'use client';
+/**
+ * Sync the BulkRunsHub filter + timeRange state with the URL search
+ * params so the filtered view is refresh-stable and shareable.
+ *
+ * BR-7 (v1.2.6): before the fix, every filter (status pill, mode pill,
+ * since, until, hasFailures, triggeredBy) lived in React state only.
+ * Refresh or share-the-link dropped the filter; editors couldn't send
+ * "failed runs in May" as a URL.
+ *
+ * Contract:
+ *   - The hook owns READ + WRITE of the filter / timeRange tuple. The
+ *     component holds NO local React state for these — it reads from
+ *     the hook and writes back via the returned setters.
+ *   - URL writes use `router.replace(..., { scroll: false })` so the
+ *     browser doesn't push a history entry per pill click and so the
+ *     page doesn't jump to the top on every state update.
+ *   - Empty / default values are omitted from the URL to keep it readable
+ *     (`?status=failed&since=2026-05-01` is friendlier than the same
+ *     plus six empty params).
+ *   - SSR-safe: when `usePathname()` / `useSearchParams()` return null
+ *     (first render in some App Router edge cases), we fall back to the
+ *     defaults so the table doesn't render with `undefined` filter state.
+ *
+ * The pure serializers live in `./urlFilters.ts` so they can be unit
+ * tested without dragging `next/navigation` into the node test
+ * environment.
+ */ import { usePathname, useRouter, useSearchParams } from 'next/navigation';
+import { useCallback, useMemo } from 'react';
+import { buildSearchString, DEFAULT_FILTERS, readFilters, readTimeRange } from './urlFilters.js';
+export { DEFAULT_FILTERS } from './urlFilters.js';
+export function useUrlFilters() {
+    const router = useRouter();
+    const pathname = usePathname();
+    const searchParams = useSearchParams();
+    const filters = useMemo(()=>{
+        return readFilters(searchParams ? new URLSearchParams(searchParams.toString()) : new URLSearchParams());
+    }, [
+        searchParams
+    ]);
+    const timeRange = useMemo(()=>{
+        return readTimeRange(searchParams ? new URLSearchParams(searchParams.toString()) : new URLSearchParams());
+    }, [
+        searchParams
+    ]);
+    const writeUrl = useCallback((nextFilters, nextRange)=>{
+        const qs = buildSearchString(nextFilters, nextRange);
+        // `pathname` can be null in some App Router edge cases (e.g. when
+        // the hook fires before the router context is ready). Skip the
+        // navigation in that case — next render will hit the path branch.
+        if (!pathname) return;
+        router.replace(`${pathname}${qs}`, {
+            scroll: false
+        });
+    }, [
+        pathname,
+        router
+    ]);
+    const setFilters = useCallback((patch)=>{
+        const next = {
+            ...filters,
+            ...patch
+        };
+        writeUrl(next, timeRange);
+    }, [
+        filters,
+        timeRange,
+        writeUrl
+    ]);
+    const setTimeRange = useCallback((range)=>{
+        writeUrl(filters, range);
+    }, [
+        filters,
+        writeUrl
+    ]);
+    const clearAll = useCallback(()=>{
+        writeUrl(DEFAULT_FILTERS, '7d');
+    }, [
+        writeUrl
+    ]);
+    return {
+        filters,
+        timeRange,
+        setFilters,
+        setTimeRange,
+        clearAll
+    };
+}

package/dist/views/TranslationHub/ActiveJobs.d.ts

@@ -0,0 +1,6 @@
+import type React from 'react';
+interface Props {
+    basePath: string;
+}
+export declare const ActiveJobs: React.FC<Props>;
+export {};

package/dist/views/TranslationHub/ActiveJobs.js

@@ -0,0 +1,320 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { useEffect, useState } from 'react';
+import { readResponseError } from '../shared/fetch-error-body.js';
+// Active polling cadence — used while at least one job is `running`.
+// 5s matches the "refresh every 5s" copy in the header.
+const POLL_INTERVAL_MS = 5000;
+// Idle cadence — used when no jobs are running. Pre-1.2.8 the loop
+// re-queued at POLL_INTERVAL_MS unconditionally, so the page hammered
+// `/api/ai-translate-jobs` every 5s for the entire time the Hub was
+// open — even hours after the last job finished. Under a bulk run with
+// many concurrent admin tabs that crashed the server. We still need to
+// poll when idle (a job can be triggered from another tab and the
+// In-flight panel must reflect it), but the cadence can be much
+// slower.
+const IDLE_POLL_INTERVAL_MS = 60_000;
+const SECTION_STYLE = {
+    background: 'var(--theme-elevation-50)',
+    border: '1px solid var(--theme-elevation-150)',
+    borderRadius: '6px',
+    padding: '1rem'
+};
+const ROW_STYLE = {
+    display: 'grid',
+    gridTemplateColumns: '1fr 0.7fr 1.2fr 0.8fr 0.6fr',
+    gap: '0.75rem',
+    padding: '0.5rem 0',
+    alignItems: 'center',
+    fontSize: '0.875rem',
+    borderTop: '1px solid var(--theme-elevation-100)',
+    color: 'var(--theme-elevation-800)'
+};
+const HEADER_ROW_STYLE = {
+    ...ROW_STYLE,
+    borderTop: 'none',
+    fontSize: '0.75rem',
+    fontWeight: 600,
+    textTransform: 'uppercase',
+    letterSpacing: '0.05em',
+    color: 'var(--theme-elevation-500)'
+};
+const STATUS_COLORS = {
+    running: 'var(--theme-warning-500, #d97706)',
+    completed: 'var(--theme-success-500, #16a34a)',
+    failed: 'var(--theme-error-500, #b91c1c)',
+    stale: 'var(--theme-elevation-500)'
+};
+// Threshold for treating a `running` job as stuck/zombied. The cms-plugins
+// persistJobs feature writes a row when a job starts but doesn't sweep it
+// on server-restart, so a translate that crashed mid-flight stays
+// `running` in the DB forever. Operationally any real translate finishes
+// in seconds; anything over 5 minutes is dead.
+const STALE_AFTER_MS = 5 * 60 * 1000;
+function effectiveStatus(j) {
+    if (j.status !== 'running') {
+        return j.status;
+    }
+    const startedMs = new Date(j.startedAt ?? j.createdAt).getTime();
+    return Date.now() - startedMs > STALE_AFTER_MS ? 'stale' : 'running';
+}
+// Builds the jobs-list URL for the last 15-minute window. Extracted to
+// keep `fetchOnce` under biome's cognitive-complexity ceiling.
+function buildJobsUrl(basePath) {
+    const since = new Date(Date.now() - 15 * 60 * 1000).toISOString();
+    // Bumped from 10 → 50 — during bulk-publish bursts more than 10 jobs
+    // can be in flight concurrently. Without headroom the in-flight
+    // panel quietly drops older `running` jobs.
+    const params = new URLSearchParams({
+        'where[createdAt][greater_than]': since,
+        limit: '50',
+        sort: '-createdAt',
+        depth: '0'
+    });
+    return `${basePath}/api/ai-translate-jobs?${params.toString()}`;
+}
+function relTime(iso) {
+    const diff = Date.now() - new Date(iso).getTime();
+    const s = Math.floor(diff / 1000);
+    if (s < 60) {
+        return `${s}s ago`;
+    }
+    if (s < 3600) {
+        return `${Math.floor(s / 60)}m ago`;
+    }
+    if (s < 86_400) {
+        return `${Math.floor(s / 3600)}h ago`;
+    }
+    return `${Math.floor(s / 86_400)}d ago`;
+}
+export const ActiveJobs = ({ basePath })=>{
+    const [jobs, setJobs] = useState(null);
+    const [error, setError] = useState(null);
+    useEffect(()=>{
+        let cancelled = false;
+        let timer;
+        // Tracks whether the most recent poll saw any `running` job. The
+        // next setTimeout uses this to pick the active vs idle cadence.
+        let hasActiveJob = false;
+        async function fetchJobs() {
+            const res = await fetch(buildJobsUrl(basePath), {
+                credentials: 'include'
+            });
+            if (!res.ok) {
+                throw new Error(await readResponseError(res));
+            }
+            const data = await res.json();
+            return data.docs ?? [];
+        }
+        async function fetchOnce() {
+            try {
+                const docs = await fetchJobs();
+                if (cancelled) {
+                    return;
+                }
+                setJobs(docs);
+                setError(null);
+                hasActiveJob = docs.some((j)=>j.status === 'running');
+            } catch (e) {
+                if (!cancelled) {
+                    setError(e instanceof Error ? e.message : String(e));
+                }
+            } finally{
+                // Visibility-aware polling: skip polling when the tab is
+                // hidden — `fetchOnce` re-fires from `onVisibility` below when
+                // the tab returns to foreground.
+                //
+                // Cadence-aware polling: 5s while a job is in flight, 60s once
+                // every job has terminated. Avoids hammering the endpoint
+                // forever while the Hub sits idle.
+                if (!cancelled && document.visibilityState === 'visible') {
+                    const nextDelay = hasActiveJob ? POLL_INTERVAL_MS : IDLE_POLL_INTERVAL_MS;
+                    timer = setTimeout(fetchOnce, nextDelay);
+                }
+            }
+        }
+        function onVisibility() {
+            if (document.visibilityState === 'visible' && !cancelled) {
+                // Tab came back to foreground — fire one fresh poll and the
+                // chain re-starts from there.
+                if (timer) {
+                    clearTimeout(timer);
+                }
+                fetchOnce();
+            }
+        }
+        document.addEventListener('visibilitychange', onVisibility);
+        fetchOnce();
+        return ()=>{
+            cancelled = true;
+            if (timer) {
+                clearTimeout(timer);
+            }
+            document.removeEventListener('visibilitychange', onVisibility);
+        };
+    }, [
+        basePath
+    ]);
+    const running = jobs?.filter((j)=>effectiveStatus(j) === 'running') ?? [];
+    const stale = jobs?.filter((j)=>effectiveStatus(j) === 'stale') ?? [];
+    const recent = jobs ?? [];
+    return /*#__PURE__*/ _jsxs("section", {
+        style: SECTION_STYLE,
+        children: [
+            /*#__PURE__*/ _jsxs("header", {
+                style: {
+                    display: 'flex',
+                    alignItems: 'center',
+                    justifyContent: 'space-between',
+                    marginBottom: '0.75rem'
+                },
+                children: [
+                    /*#__PURE__*/ _jsx("h2", {
+                        style: {
+                            margin: 0,
+                            fontSize: '1rem',
+                            color: 'var(--theme-elevation-1000)'
+                        },
+                        children: "In-flight"
+                    }),
+                    /*#__PURE__*/ _jsx("span", {
+                        style: {
+                            fontSize: '0.75rem',
+                            color: 'var(--theme-elevation-500)'
+                        },
+                        children: (()=>{
+                            if (jobs === null) {
+                                return 'Loading…';
+                            }
+                            // Cadence text mirrors the actual poll interval so the user
+                            // isn't misled into thinking we're hammering the server.
+                            // While idle (no `running` jobs) we back off to 60s; the
+                            // first newly-enqueued job is picked up by the next tick.
+                            const cadence = running.length > 0 ? '5s' : '60s';
+                            if (stale.length > 0) {
+                                return `${running.length} running · ${stale.length} stale · refresh every ${cadence}`;
+                            }
+                            return `${running.length} running · refresh every ${cadence}`;
+                        })()
+                    })
+                ]
+            }),
+            error && /*#__PURE__*/ _jsx("p", {
+                style: {
+                    color: 'var(--theme-error-500, #b91c1c)',
+                    fontSize: '0.875rem',
+                    margin: '0 0 0.5rem'
+                },
+                children: error
+            }),
+            recent.length === 0 ? /*#__PURE__*/ _jsx("p", {
+                style: {
+                    margin: 0,
+                    color: 'var(--theme-elevation-500)',
+                    fontSize: '0.875rem'
+                },
+                children: "Nothing in flight. Translations finish in seconds; historical runs live in the Recent translations table below."
+            }) : /*#__PURE__*/ _jsxs(_Fragment, {
+                children: [
+                    /*#__PURE__*/ _jsxs("div", {
+                        style: HEADER_ROW_STYLE,
+                        children: [
+                            /*#__PURE__*/ _jsx("span", {
+                                children: "Collection / doc"
+                            }),
+                            /*#__PURE__*/ _jsx("span", {
+                                children: "Status"
+                            }),
+                            /*#__PURE__*/ _jsx("span", {
+                                children: "Progress"
+                            }),
+                            /*#__PURE__*/ _jsx("span", {
+                                children: "Started"
+                            }),
+                            /*#__PURE__*/ _jsx("span", {
+                                style: {
+                                    textAlign: 'right'
+                                },
+                                children: "Locales"
+                            })
+                        ]
+                    }),
+                    recent.map((j)=>{
+                        const completed = Array.isArray(j.completedLocales) ? j.completedLocales.length : 0;
+                        const failed = Array.isArray(j.failedLocales) ? j.failedLocales.length : 0;
+                        const progress = `${completed}/${j.totalLocales}`;
+                        const eff = effectiveStatus(j);
+                        return /*#__PURE__*/ _jsxs("div", {
+                            style: ROW_STYLE,
+                            children: [
+                                /*#__PURE__*/ _jsxs("span", {
+                                    style: {
+                                        overflow: 'hidden',
+                                        textOverflow: 'ellipsis'
+                                    },
+                                    children: [
+                                        /*#__PURE__*/ _jsx("code", {
+                                            style: {
+                                                fontSize: '0.75rem'
+                                            },
+                                            children: j.collection
+                                        }),
+                                        ' ',
+                                        /*#__PURE__*/ _jsxs("span", {
+                                            style: {
+                                                color: 'var(--theme-elevation-500)'
+                                            },
+                                            children: [
+                                                "#",
+                                                j.documentId
+                                            ]
+                                        })
+                                    ]
+                                }),
+                                /*#__PURE__*/ _jsxs("span", {
+                                    style: {
+                                        color: STATUS_COLORS[eff],
+                                        fontWeight: 500
+                                    },
+                                    children: [
+                                        eff === 'stale' ? 'stale (server died)' : eff,
+                                        failed > 0 ? ` (${failed} failed)` : ''
+                                    ]
+                                }),
+                                /*#__PURE__*/ _jsxs("span", {
+                                    children: [
+                                        progress,
+                                        Array.isArray(j.completedLocales) && j.completedLocales.length > 0 && /*#__PURE__*/ _jsxs("span", {
+                                            style: {
+                                                marginLeft: '0.5rem',
+                                                color: 'var(--theme-elevation-500)',
+                                                fontSize: '0.75rem'
+                                            },
+                                            children: [
+                                                "(",
+                                                j.completedLocales.join(', '),
+                                                ")"
+                                            ]
+                                        })
+                                    ]
+                                }),
+                                /*#__PURE__*/ _jsx("span", {
+                                    style: {
+                                        color: 'var(--theme-elevation-500)'
+                                    },
+                                    children: relTime(j.startedAt ?? j.createdAt)
+                                }),
+                                /*#__PURE__*/ _jsx("span", {
+                                    style: {
+                                        textAlign: 'right'
+                                    },
+                                    children: j.totalLocales
+                                })
+                            ]
+                        }, j.id);
+                    })
+                ]
+            })
+        ]
+    });
+};

package/dist/views/TranslationHub/AdvancedPanel.d.ts

@@ -0,0 +1,17 @@
+import type React from 'react';
+/**
+ * Advanced tab content. Real diagnostic and developer surfaces, not just
+ * a link dump. Aimed at the admin trying to answer:
+ *   - "Is the plugin healthy right now?"
+ *   - "How big are the bookkeeping tables?"
+ *   - "Are there stale running jobs from a crashed worker?"
+ *   - "How do I force re-translate everything ignoring the hash skip?"
+ *
+ * Pulls live counts from the various plugin-owned collections (only
+ * totals — no row content — to keep this cheap).
+ */
+interface Props {
+    basePath: string;
+}
+export declare const AdvancedPanel: React.FC<Props>;
+export default AdvancedPanel;