@purposeinplay/payload-ai-translate 0.1.0

package/dist/views/BulkRunsHub/bucket-grouping.js

@@ -0,0 +1,344 @@
+/**
+ * Group a flat list of `BatchJobSummary` units into a 2-level tree:
+ *
+ *   Bucket (collection or global)
+ *     └── Document
+ *           └── Locales (rendered inline as chips, not as separate rows)
+ *
+ * Editor mental model is collection-shaped, not unit-shaped — direct quote:
+ * "let's say 50 docs from one collection fail but 150 are completed maybe
+ * I want to trigger retry for those 50 easily." The flat list doesn't
+ * surface that grouping; this helper does.
+ *
+ * Heuristic for distinguishing globals from collections: the worker stores
+ * `documentId === collection` for globals (the slug doubles as the id),
+ * whereas collections have a numeric / UUID document id. Confirmed against
+ * `api.ts:translateGlobal` which returns
+ * `{ documentId: options.global, collection: options.global, ... }`.
+ */ import { formatDuration } from '../shared/format.js';
+/**
+ * Resolve the bucket header count for the active filter pill. Returns a
+ * UNIT-level count (the historical semantics — `succeededCount`,
+ * `failedCount` etc. on the bucket are unit-based). When the filter is
+ * `all`, returns `totalUnits`. Otherwise returns the matching scalar.
+ *
+ * Doc-level counts (`docCountsByStatus`) stay on the bucket for callers
+ * that need "how many distinct docs match this filter" — e.g. the
+ * `shouldBucketBeVisibleUnderFilter` rule below, which has to know
+ * whether any docs at all will render under the active filter.
+ */ export function getBucketCountForFilter(bucket, filter) {
+    switch(filter){
+        case 'all':
+            return bucket.totalUnits;
+        case 'completed':
+            return bucket.succeededCount;
+        case 'failed':
+            return bucket.failedCount;
+        case 'pending':
+            return bucket.pendingCount;
+        case 'running':
+            return bucket.runningCount;
+        case 'skipped':
+            return bucket.skippedCount;
+        case 'reverted':
+            return bucket.revertedCount;
+    }
+}
+/**
+ * Decide whether a bucket should render at all under the active filter.
+ * Hides buckets that have zero matching docs when a non-`all` filter is
+ * active — the previous behaviour rendered the bucket header with stale
+ * unfiltered counts, contradicting the global "No units match" message
+ * below. With this rule the entire bucket disappears, and the global
+ * empty state surfaces only when EVERY bucket is empty.
+ *
+ * Uses the DOC count rather than the unit count because the expanded
+ * panel renders one row per doc. A bucket with one doc whose only
+ * failed locale we'd be looking at is still worth showing — but only
+ * if at least one such doc exists.
+ */ export function shouldBucketBeVisibleUnderFilter(bucket, filter) {
+    if (filter === 'all') return true;
+    return (bucket.docCountsByStatus[filter] ?? 0) > 0;
+}
+/**
+ * Group the flat `jobs` array into buckets, using backend
+ * `countsByCollection` for the authoritative per-bucket totals.
+ *
+ * Two passes:
+ *   1. Seed every bucket from `countsByCollection` (the FULL totals
+ *      across the batch — not just the paginated `jobs` page). This
+ *      ensures bucket headers show correct counts even when the
+ *      `jobs` page only contains a subset.
+ *   2. Walk `jobs` and attach the loaded docs to their buckets.
+ *      `bucket.loadedDocs < bucket.totalDocs` when the page hasn't
+ *      loaded every doc in the bucket — UI surfaces this gap.
+ *
+ * Sort order:
+ *   1. Buckets with failures come first (descending failure count).
+ *   2. Then collections alphabetically.
+ *   3. Then globals alphabetically (any bucket with `isGlobal: true`).
+ *
+ * Within a bucket, docs are kept in their original insertion order from
+ * the `jobs` array — Payload's status endpoint already sorts by unit id
+ * (closely aligned with creation order), which is a reasonable default.
+ */ export function groupJobsIntoBuckets(jobs, countsByCollection = {}) {
+    const byCollection = new Map();
+    // Pass 1: seed every bucket from the backend's authoritative totals.
+    // `countsByCollection` is the only reliable source for total docs per
+    // collection — the paginated jobs page may miss most of them.
+    for (const [collection, counts] of Object.entries(countsByCollection)){
+        // v1.2.7: `docCountsByStatus` is optional on pre-1.2.7 backends —
+        // derive a best-effort shape from the scalar unit counts so the
+        // filter-aware bucket header still renders something sensible (it
+        // becomes unit-count rather than doc-count, but never zeroes out
+        // a populated bucket).
+        const docCountsByStatus = counts.docCountsByStatus ?? {
+            all: counts.totalDocs,
+            pending: counts.pending,
+            running: counts.running,
+            completed: counts.succeeded,
+            failed: counts.failed,
+            skipped: counts.skipped,
+            reverted: counts.reverted
+        };
+        byCollection.set(collection, {
+            collection,
+            isGlobal: counts.isGlobal,
+            docs: new Map(),
+            totalUnits: counts.total,
+            succeededCount: counts.succeeded,
+            failedCount: counts.failed,
+            pendingCount: counts.pending,
+            runningCount: counts.running,
+            skippedCount: counts.skipped,
+            revertedCount: counts.reverted,
+            totalDocs: counts.totalDocs,
+            loadedDocs: 0,
+            topFailureCodes: counts.topFailureCodes,
+            distinctFailureCodes: counts.distinctFailureCodes,
+            collectionSpanMs: counts.collectionSpanMs,
+            aiActiveMs: counts.aiActiveMs,
+            queueWaitMs: counts.queueWaitMs,
+            docCountsByStatus
+        });
+    }
+    // Pass 2: attach loaded docs to their buckets. Also handle the legacy
+    // path where `countsByCollection` is empty (e.g. older API response) —
+    // fall back to bucket creation from jobs as best-effort.
+    for (const job of jobs){
+        const collection = job.collection;
+        const isGlobal = job.documentId === job.collection;
+        let bucket = byCollection.get(collection);
+        if (!bucket) {
+            // Fallback: no backend counts for this collection (legacy or
+            // race). Seed from jobs only — counts will reflect loaded page.
+            bucket = {
+                collection,
+                isGlobal,
+                docs: new Map(),
+                totalUnits: 0,
+                succeededCount: 0,
+                failedCount: 0,
+                pendingCount: 0,
+                runningCount: 0,
+                skippedCount: 0,
+                revertedCount: 0,
+                totalDocs: 0,
+                loadedDocs: 0,
+                topFailureCodes: [],
+                distinctFailureCodes: 0,
+                collectionSpanMs: null,
+                aiActiveMs: null,
+                queueWaitMs: null,
+                docCountsByStatus: {
+                    all: 0,
+                    pending: 0,
+                    running: 0,
+                    completed: 0,
+                    failed: 0,
+                    skipped: 0,
+                    reverted: 0
+                }
+            };
+            byCollection.set(collection, bucket);
+        }
+        let doc = bucket.docs.get(job.documentId);
+        if (!doc) {
+            doc = {
+                collection,
+                documentId: job.documentId,
+                jobs: [],
+                failedLocaleCount: 0,
+                succeededLocaleCount: 0,
+                docSpanMs: null,
+                docAiActiveMs: null,
+                docQueueWaitMs: null,
+                totalCostUsd: 0,
+                maxAttempts: 0
+            };
+            bucket.docs.set(job.documentId, doc);
+            bucket.loadedDocs += 1;
+        }
+        doc.jobs.push(job);
+        // Per-locale aggregates rolled up to per-doc.
+        if (job.status === 'success') doc.succeededLocaleCount += 1;
+        else if (job.status === 'failed') doc.failedLocaleCount += 1;
+        if (typeof job.processingDurationMs === 'number' && job.processingDurationMs > 0) {
+            doc.docAiActiveMs = (doc.docAiActiveMs ?? 0) + job.processingDurationMs;
+        }
+        if (typeof job.costUsd === 'number') {
+            doc.totalCostUsd += job.costUsd;
+        }
+        if (job.attempts > doc.maxAttempts) doc.maxAttempts = job.attempts;
+        // When countsByCollection wasn't provided, also bump the bucket
+        // counts from jobs (legacy fallback).
+        const hasBackendCounts = bucket.totalUnits > 0;
+        if (!hasBackendCounts) {
+            bucket.totalUnits += 1;
+            if (job.status === 'success') bucket.succeededCount += 1;
+            else if (job.status === 'failed') bucket.failedCount += 1;
+            else if (job.status === 'pending') bucket.pendingCount += 1;
+            else if (job.status === 'running') bucket.runningCount += 1;
+            else if (job.status === 'skipped') bucket.skippedCount += 1;
+        }
+    }
+    // v1.2.7: legacy-mode docCountsByStatus rebuild — when the backend
+    // didn't provide `docCountsByStatus` we ALSO compute it from the
+    // loaded jobs so the filter pill reflects what the user can see. For
+    // backend-seeded buckets, the authoritative counts already won during
+    // pass 1; we only refill when the all-status count is still zero
+    // (= legacy fallback path).
+    for (const bucket of byCollection.values()){
+        if (bucket.docCountsByStatus.all !== 0) continue;
+        const byStatus = {
+            all: new Set(),
+            pending: new Set(),
+            running: new Set(),
+            completed: new Set(),
+            failed: new Set(),
+            skipped: new Set(),
+            reverted: new Set()
+        };
+        for (const doc of bucket.docs.values()){
+            byStatus.all.add(doc.documentId);
+            for (const job of doc.jobs){
+                if (job.status === 'success') byStatus.completed.add(doc.documentId);
+                else if (job.status === 'failed') byStatus.failed.add(doc.documentId);
+                else if (job.status === 'pending') byStatus.pending.add(doc.documentId);
+                else if (job.status === 'running') byStatus.running.add(doc.documentId);
+                else if (job.status === 'skipped') byStatus.skipped.add(doc.documentId);
+                else if (job.status === 'reverted') byStatus.reverted.add(doc.documentId);
+            }
+        }
+        bucket.docCountsByStatus = {
+            all: byStatus.all.size,
+            pending: byStatus.pending.size,
+            running: byStatus.running.size,
+            completed: byStatus.completed.size,
+            failed: byStatus.failed.size,
+            skipped: byStatus.skipped.size,
+            reverted: byStatus.reverted.size
+        };
+    }
+    // For fallback buckets (no backend counts), totalDocs is at least
+    // loadedDocs so the "Showing X of Y" hint doesn't false-trigger.
+    // Also compute the per-doc span here — only doable once we've seen
+    // every locale for the doc.
+    for (const bucket of byCollection.values()){
+        if (bucket.totalDocs < bucket.loadedDocs) {
+            bucket.totalDocs = bucket.loadedDocs;
+        }
+        for (const doc of bucket.docs.values()){
+            let minStartedAt = null;
+            let maxCompletedAt = null;
+            for (const job of doc.jobs){
+                if (job.startedAt) {
+                    const ms = new Date(job.startedAt).getTime();
+                    if (Number.isFinite(ms)) {
+                        if (minStartedAt === null || ms < minStartedAt) minStartedAt = ms;
+                    }
+                }
+                if (job.completedAt) {
+                    const ms = new Date(job.completedAt).getTime();
+                    if (Number.isFinite(ms)) {
+                        if (maxCompletedAt === null || ms > maxCompletedAt) maxCompletedAt = ms;
+                    }
+                }
+            }
+            if (minStartedAt !== null && maxCompletedAt !== null) {
+                doc.docSpanMs = Math.max(0, maxCompletedAt - minStartedAt);
+                if (doc.docAiActiveMs !== null) {
+                    doc.docQueueWaitMs = Math.max(0, doc.docSpanMs - doc.docAiActiveMs);
+                }
+            }
+        }
+    }
+    return [
+        ...byCollection.values()
+    ].sort((a, b)=>{
+        if (a.failedCount > 0 && b.failedCount === 0) return -1;
+        if (a.failedCount === 0 && b.failedCount > 0) return 1;
+        if (a.failedCount !== b.failedCount) {
+            return b.failedCount - a.failedCount;
+        }
+        if (a.isGlobal !== b.isGlobal) return a.isGlobal ? 1 : -1;
+        return a.collection.localeCompare(b.collection);
+    });
+}
+/**
+ * Whether a bucket should start expanded on initial render. Per UX
+ * recommendation: failed buckets expanded by default (problem is on
+ * screen without clicking), all-success buckets collapsed (don't
+ * clutter the triage view).
+ */ export function shouldBucketBeExpandedByDefault(bucket) {
+    return bucket.failedCount > 0 || bucket.runningCount > 0;
+}
+// ---------------------------------------------------------------------------
+// Bucket-header runtime label helpers — extracted so the BucketRow
+// component can render them consistently and so they can be unit-tested.
+// All three deal with the same edge case: the server-aggregated
+// `aiActiveMs` sums per-unit processing time, which can exceed
+// `collectionSpanMs` when units ran in parallel across workers. The
+// server clamps `queueWaitMs` to `max(0, span − ai)` but doesn't touch
+// the raw AI number; the display layer is responsible for keeping the
+// AI / span / queue-wait numbers internally consistent. See NEW-11.
+// ---------------------------------------------------------------------------
+/**
+ * Compact duration helper used by `fmtBucketAiActive` /
+ * `fmtBucketQueued`. Thin wrapper around the shared `formatDuration`
+ * helper — kept as a separate export so the bucket-grouping module
+ * doesn't need to import from `views/shared/format.ts` directly at
+ * every call site, and so the bucket-runtime tests keep their
+ * historical name. NEW-18 (v1.2.6): carries minutes → hours → days
+ * via the shared helper; the legacy implementation capped at minutes
+ * (`964m 6s`).
+ */ export function fmtBucketDurationShort(ms) {
+    return formatDuration(ms);
+}
+/**
+ * Render the bucket header "AI active" cell. When `aiActiveMs` exceeds
+ * `collectionSpanMs` (parallelism), present as `≈<span>` rather than a
+ * number that visually contradicts the total wallclock. The raw numbers
+ * are unchanged; the tooltip still shows both.
+ */ export function fmtBucketAiActive(bucket) {
+    const ai = bucket.aiActiveMs;
+    const span = bucket.collectionSpanMs;
+    if (ai == null) return '—';
+    if (span != null && ai > span) {
+        return `≈${fmtBucketDurationShort(span)}`;
+    }
+    return fmtBucketDurationShort(ai);
+}
+/**
+ * Render the bucket header "Queued" cell. Uses the server-clamped queue
+ * wait but renders `0` as `'0s'` (instead of `'—'`) so editors can tell
+ * "no wait" from "data missing." When AI overran span, the queue wait
+ * is necessarily zero — surface that explicitly.
+ */ export function fmtBucketQueued(bucket) {
+    if (bucket.aiActiveMs != null && bucket.collectionSpanMs != null && bucket.aiActiveMs > bucket.collectionSpanMs) {
+        return '0s';
+    }
+    if (bucket.queueWaitMs == null) return '—';
+    if (bucket.queueWaitMs === 0) return '0s';
+    return fmtBucketDurationShort(bucket.queueWaitMs);
+}

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

@@ -0,0 +1,9 @@
+export type FailureCodeCount = {
+    code: string;
+    count: number;
+};
+export type BucketFailureSummaryEntry = {
+    title: string;
+    count: number;
+};
+export declare function summarizeBucketFailureTypes(topFailureCodes: ReadonlyArray<FailureCodeCount>, batchStatus: string | null | undefined): BucketFailureSummaryEntry[];

package/dist/views/BulkRunsHub/bucketFailureSummary.js

@@ -0,0 +1,36 @@
+/**
+ * Pure helper for the BucketRow bucket-summary "X different error types"
+ * line (ROUND3-8). Extracted so the grouping logic — which routes the
+ * persisted `failureCode`s through `categorizeFailure` and then sums by
+ * the friendly title — has a unit-test pin without needing to mount the
+ * React component.
+ *
+ * Before this helper, BucketRow looked up each raw failureCode via
+ * `editorCodeFromFailureCode` directly and rendered titles like
+ * "Translation system is not set up" for cancel-mid-flight units while
+ * the unit-level drill-down (which uses `categorizeFailure` with
+ * `batchStatus` threaded through) correctly said "Stopped mid-run".
+ * Editors who didn't drill in saw a misleading config-broken signal.
+ *
+ * Two raw codes can collapse to the same friendly bucket post-
+ * categorisation (e.g. when the parent is cancelled, every code maps
+ * to `cancelled-mid-flight`). We group by the rendered title so we
+ * don't double-count.
+ */ import { categorizeFailure, editorMessageFor } from '../../lib/error-messages.js';
+export function summarizeBucketFailureTypes(topFailureCodes, batchStatus) {
+    const groupedCounts = new Map();
+    for (const tf of topFailureCodes){
+        const categorized = categorizeFailure({
+            failureCode: tf.code,
+            batchStatus: batchStatus ?? null
+        });
+        const title = editorMessageFor(categorized.editorCode).title;
+        groupedCounts.set(title, (groupedCounts.get(title) ?? 0) + tf.count);
+    }
+    return [
+        ...groupedCounts.entries()
+    ].map(([title, count])=>({
+            title,
+            count
+        }));
+}

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

@@ -0,0 +1,5 @@
+export declare function dedupedStatusFetch(url: string): Promise<Response>;
+/** Test-only: reset the dedup window between tests. */
+export declare function __resetBatchStatusInFlightForTests(): void;
+/** Test-only: snapshot of currently in-flight URLs. */
+export declare function __getBatchStatusInFlightUrlsForTests(): string[];

package/dist/views/BulkRunsHub/dedupedStatusFetch.js

@@ -0,0 +1,45 @@
+/**
+ * ROUND3-6: Module-level dedup for the per-batch
+ * `/api/translation-hub/bulk-translate/{id}/status` fetch.
+ *
+ * Under React 18 StrictMode dev the DrillDown effect runs → cleanup →
+ * effect-again, and the first run's in-flight `fetch` doesn't abort
+ * cleanly (the request has already left the wire). The result was a
+ * paired-burst pattern on every row-expand — same pathology as NEW-5
+ * (active-poller) and ROUND2-4 (usage-summary) but on the per-batch
+ * status endpoint, which Group G's `useBulkTranslateActive` singleton
+ * doesn't cover.
+ *
+ * The map below stores the in-flight `Promise<Response>` keyed by URL.
+ * The second concurrent caller re-uses the first one instead of firing
+ * again. The dedup window is "concurrent calls during the same render
+ * flush", not "cache forever" — entries clear the instant the promise
+ * settles.
+ */ const inFlightStatusRequests = new Map();
+export function dedupedStatusFetch(url) {
+    const existing = inFlightStatusRequests.get(url);
+    if (existing) {
+        // Hand back a fresh clone so each caller can read the body without
+        // racing on the single underlying ReadableStream.
+        return existing.then((res)=>res.clone());
+    }
+    const p = fetch(url, {
+        credentials: 'include'
+    });
+    inFlightStatusRequests.set(url, p);
+    // Clear the in-flight entry once settled, success or failure.
+    p.finally(()=>{
+        if (inFlightStatusRequests.get(url) === p) {
+            inFlightStatusRequests.delete(url);
+        }
+    }).catch(()=>undefined);
+    return p.then((res)=>res.clone());
+}
+/** Test-only: reset the dedup window between tests. */ export function __resetBatchStatusInFlightForTests() {
+    inFlightStatusRequests.clear();
+}
+/** Test-only: snapshot of currently in-flight URLs. */ export function __getBatchStatusInFlightUrlsForTests() {
+    return [
+        ...inFlightStatusRequests.keys()
+    ];
+}

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

@@ -0,0 +1,17 @@
+import type { AdminViewServerProps } from 'payload';
+import type React from 'react';
+/**
+ * Server entry for the custom `/admin/translation/runs` view.
+ *
+ * Wraps the client UI in Payload's `<DefaultTemplate>` so the page
+ * inherits the standard admin chrome (sidebar nav, top bar, breadcrumbs).
+ *
+ * Auth (1.2.8): admin and editor roles. Pre-1.2.8 was admin-only.
+ * Threaded role + identity into the client so the run list can:
+ *   1. Render an attribution chip on every row (`by alice@…`).
+ *   2. Hide the action menu (cancel / retry / revert) on rows the
+ *      current viewer doesn't own — only admins or the original
+ *      triggering editor can mutate a run.
+ */
+export declare const BulkRunsHubView: React.FC<AdminViewServerProps>;
+export default BulkRunsHubView;

package/dist/views/BulkRunsHub/index.js

@@ -0,0 +1,80 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { DefaultTemplate } from '@payloadcms/next/templates';
+// Self-import via the package's external subpath — keeps the "use client"
+// directive intact at runtime. Mirrors the same pattern in
+// `views/TranslationHub/index.tsx`.
+import { BulkRunsHubClient } from '@purposeinplay/payload-ai-translate/views-client';
+import { redirect } from 'next/navigation';
+import { formatAdminURL } from 'payload/shared';
+/**
+ * Server entry for the custom `/admin/translation/runs` view.
+ *
+ * Wraps the client UI in Payload's `<DefaultTemplate>` so the page
+ * inherits the standard admin chrome (sidebar nav, top bar, breadcrumbs).
+ *
+ * Auth (1.2.8): admin and editor roles. Pre-1.2.8 was admin-only.
+ * Threaded role + identity into the client so the run list can:
+ *   1. Render an attribution chip on every row (`by alice@…`).
+ *   2. Hide the action menu (cancel / retry / revert) on rows the
+ *      current viewer doesn't own — only admins or the original
+ *      triggering editor can mutate a run.
+ */ export const BulkRunsHubView = ({ initPageResult, params, searchParams })=>{
+    const { req, visibleEntities, permissions } = initPageResult;
+    // Payload renders CUSTOM admin views as PUBLIC by default — unlike
+    // built-in collection/global routes, which redirect unauthenticated
+    // visitors to login. Without this check, anonymous visitors got the
+    // full admin shell (nav with every collection/global name) plus this
+    // view's role message. Mirror the built-in behaviour: no user → login,
+    // preserving the deep link via ?redirect=.
+    if (!req.user) {
+        const adminRoute = req.payload.config.routes?.admin ?? '/admin';
+        redirect(formatAdminURL({
+            adminRoute,
+            path: `/login?redirect=${encodeURIComponent(`${adminRoute}/translation-runs`)}`
+        }));
+    }
+    const user = req.user;
+    const roles = user?.roles ?? [];
+    const isAdmin = roles.includes('admin');
+    const isEditor = roles.includes('editor');
+    const isPermitted = isAdmin || isEditor;
+    const role = isAdmin ? 'admin' : 'editor';
+    return /*#__PURE__*/ _jsx(DefaultTemplate, {
+        i18n: req.i18n,
+        locale: req.locale,
+        params: params,
+        payload: req.payload,
+        permissions: permissions,
+        searchParams: searchParams,
+        user: req.user ?? undefined,
+        visibleEntities: visibleEntities,
+        children: isPermitted ? /*#__PURE__*/ _jsx(BulkRunsHubClient, {
+            role: role,
+            currentUserId: user?.id != null ? String(user.id) : null,
+            currentUserEmail: user?.email ?? null
+        }) : /*#__PURE__*/ _jsxs("div", {
+            style: {
+                padding: '2rem',
+                maxWidth: '600px',
+                margin: '4rem auto',
+                textAlign: 'center'
+            },
+            children: [
+                /*#__PURE__*/ _jsx("h1", {
+                    style: {
+                        fontSize: '1.5rem',
+                        color: 'var(--theme-elevation-1000)'
+                    },
+                    children: "Translation Runs"
+                }),
+                /*#__PURE__*/ _jsx("p", {
+                    style: {
+                        color: 'var(--theme-elevation-700)'
+                    },
+                    children: "You need an admin or editor role to access bulk translation history."
+                })
+            ]
+        })
+    });
+};
+export default BulkRunsHubView;

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

@@ -0,0 +1,14 @@
+/**
+ * Pure serializers for the BulkRunsHub URL-state contract. v1.2.6
+ * BugIndex BR-7. Kept in a dependency-free module so the unit tests
+ * can exercise them without dragging Next.js's `next/navigation` (the
+ * test environment is node, not jsdom).
+ *
+ * The `useUrlFilters` hook is a thin shim that reads from the router,
+ * delegates to these helpers, and writes back via `router.replace`.
+ */
+import type { BulkRunsFilterState, BulkRunsTimeRange } from '../TranslationHub/BulkTranslate.types.js';
+export declare const DEFAULT_FILTERS: BulkRunsFilterState;
+export declare function readTimeRange(params: URLSearchParams): BulkRunsTimeRange;
+export declare function readFilters(params: URLSearchParams): BulkRunsFilterState;
+export declare function buildSearchString(filters: BulkRunsFilterState, timeRange: BulkRunsTimeRange): string;

package/dist/views/BulkRunsHub/urlFilters.js

@@ -0,0 +1,50 @@
+/**
+ * Pure serializers for the BulkRunsHub URL-state contract. v1.2.6
+ * BugIndex BR-7. Kept in a dependency-free module so the unit tests
+ * can exercise them without dragging Next.js's `next/navigation` (the
+ * test environment is node, not jsdom).
+ *
+ * The `useUrlFilters` hook is a thin shim that reads from the router,
+ * delegates to these helpers, and writes back via `router.replace`.
+ */ export const DEFAULT_FILTERS = {
+    status: '',
+    mode: '',
+    triggeredBy: '',
+    since: '',
+    until: '',
+    hasFailures: false
+};
+const VALID_TIME_RANGES = new Set([
+    '7d',
+    '30d',
+    'all'
+]);
+export function readTimeRange(params) {
+    const t = params.get('timeRange');
+    if (t && VALID_TIME_RANGES.has(t)) {
+        return t;
+    }
+    return '7d';
+}
+export function readFilters(params) {
+    return {
+        status: params.get('status') ?? '',
+        mode: params.get('mode') ?? '',
+        triggeredBy: params.get('triggeredBy') ?? '',
+        since: params.get('since') ?? '',
+        until: params.get('until') ?? '',
+        hasFailures: params.get('hasFailures') === 'true'
+    };
+}
+export function buildSearchString(filters, timeRange) {
+    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 (timeRange !== '7d') params.set('timeRange', timeRange);
+    const qs = params.toString();
+    return qs ? `?${qs}` : '';
+}

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

@@ -0,0 +1,26 @@
+import type { BulkRunsFilterState, BulkTranslateListResponse } from '../TranslationHub/BulkTranslate.types.js';
+export interface UseBulkRunsListResult {
+    /**
+     * Latest successful response. `null` during the initial load or when
+     * a 404 is received.
+     */
+    data: BulkTranslateListResponse | null;
+    /** True only during the first request — subsequent polls are silent. */
+    loading: boolean;
+    /** Last fetch error. Reset to `null` on next success. */
+    error: string | null;
+    /** True after `OFFLINE_THRESHOLD` consecutive failures. */
+    isOffline: boolean;
+    /** Force an immediate re-fetch (e.g. after a cancel/retry/revert action). */
+    refetch: () => void;
+    /**
+     * Load the next page and merge into `data.batches`. No-op when
+     * `data.nextCursor` is null.
+     */
+    loadMore: () => Promise<void>;
+    /** True while a loadMore request is in flight. */
+    loadingMore: boolean;
+}
+export declare function useBulkRunsList(basePath: string, filters: BulkRunsFilterState): UseBulkRunsListResult;
+export declare const BULK_RUNS_OFFLINE_THRESHOLD = 3;
+export declare const BULK_RUNS_POLL_INTERVAL_MS = 5000;