@zeniai/client-epic-state 5.2.41-beta6MM → 5.2.41-beta8MM

package/lib/esm/view/recommendation/submitRecommendationFeedbackEpic.js

@@ -1,7 +1,8 @@
-import { EMPTY } from 'rxjs';
+import { EMPTY, of } from 'rxjs';
 import { catchError, filter, mergeMap } from 'rxjs/operators';
 import { isSuccessStatus } from '../../responsePayload';
-import { submitRecommendationFeedback } from './recommendationReducer';
+import { isPromptedRecommendationFeedback, } from './recommendationPayload';
+import { submitRecommendationFeedback, submitRecommendationFeedbackCompleted, } from './recommendationReducer';
 const toRequestBody = (payload) => ({
     line_id: payload.lineId ?? null,
     dimension: payload.dimension,
@@ -33,20 +34,31 @@ const toRequestBody = (payload) => ({
     retracts_feedback_id: payload.retractsFeedbackId ?? null,
     features: payload.features ?? null,
 });
-// Fire-and-forget: the epic never re-emits an action. Feedback delivery is a
-// side-effect that must not disrupt the categorization UX, so both the
-// success and error paths complete silently (errors are logged for debugging).
+// Always reports completion so the feedback popup can show a loader and tell the
+// user what happened. The categorization itself still never waits on this: a
+// failure is surfaced in a toast rather than blocking or reverting the change.
 export const submitRecommendationFeedbackEpic = (actions$, _state$, zeniAPI) => actions$.pipe(filter(submitRecommendationFeedback.match), mergeMap((action) => {
     const { transactionId } = action.payload;
+    // Only the override that opened the popup reports completion; accepts and
+    // retractions stay fire-and-forget so they cannot settle the popup.
+    const isPrompted = isPromptedRecommendationFeedback(action.payload.outcome);
     return zeniAPI
         .postAndGetJSON(`${zeniAPI.apiEndPoints.accountMicroServiceBaseUrl}/1.0/transactions/${transactionId}/recommendation-feedback`, toRequestBody(action.payload))
         .pipe(mergeMap((response) => {
-        if (!isSuccessStatus(response)) {
+        const succeeded = isSuccessStatus(response);
+        if (!succeeded) {
             console.error('submitRecommendationFeedbackEpic: recommendation feedback was not recorded', response.status);
         }
-        return EMPTY;
+        return isPrompted
+            ? of(submitRecommendationFeedbackCompleted({
+                succeeded,
+                error: succeeded ? undefined : response.status,
+            }))
+            : EMPTY;
     }), catchError((error) => {
         console.error('submitRecommendationFeedbackEpic: failed to submit recommendation feedback', error);
-        return EMPTY;
+        return isPrompted
+            ? of(submitRecommendationFeedbackCompleted({ succeeded: false }))
+            : EMPTY;
     }));
 }));

package/lib/esm/view/spendManagement/billPay/billDetailView/billDetailViewReducer.js

@@ -18,6 +18,12 @@ const billDetailView = createSlice({
                     detail.fetchState !== 'In-Progress') {
                     draft.billDetailById[key] = {
                         ...initialBillDetailView,
+                        // Deliberately independent of the detail fetch: recommendations
+                        // are requested separately and must not be reset by a detail
+                        // refresh, which on the edit route lands right after the
+                        // recommendations request has already started.
+                        recommendationsFetchStatus: detail?.recommendationsFetchStatus ??
+                            initialBillDetailView.recommendationsFetchStatus,
                     };
                 }
             },
@@ -69,6 +75,86 @@ const billDetailView = createSlice({
                 };
             },
         },
+        fetchBillRecommendations: {
+            reducer(draft, action) {
+                const key = getBillTransactionDetailKey(action.payload.billId);
+                // The edit route can mount before the bill detail entry exists — its
+                // screen dispatches this before the parent requests the detail. Seed
+                // the entry rather than bailing, or the status would sit at
+                // `Not-Started` for the whole wait and round trip.
+                const detail = recordGet(draft.billDetailById, key, undefined) ?? {
+                    ...initialBillDetailView,
+                    billId: action.payload.billId,
+                };
+                const { fetchState } = detail.recommendationsFetchStatus;
+                // Both screens dispatch once per bill — on mount, keyed by bill id,
+                // not on every render — so this guard is not what prevents a render
+                // loop; the epic's per-bill `exhaustMap` is what collapses the two
+                // sites' dispatches into one request.
+                //
+                // `Error` is deliberately allowed through: a bill whose fetch failed
+                // must be able to try again when the screen is next opened.
+                if (action.payload.cacheOverride === true ||
+                    (fetchState !== 'In-Progress' && fetchState !== 'Completed')) {
+                    draft.billDetailById[key] = {
+                        ...detail,
+                        recommendationsFetchStatus: {
+                            fetchState: 'In-Progress',
+                            error: undefined,
+                        },
+                    };
+                }
+            },
+            prepare(billId, cacheOverride = false) {
+                return {
+                    payload: { billId, cacheOverride },
+                };
+            },
+        },
+        fetchBillRecommendationsSuccess: {
+            reducer(draft, action) {
+                const key = getBillTransactionDetailKey(action.payload.billId);
+                const detail = recordGet(draft.billDetailById, key, undefined);
+                if (detail != null) {
+                    draft.billDetailById[key] = {
+                        ...detail,
+                        recommendationsFetchStatus: {
+                            fetchState: 'Completed',
+                            error: undefined,
+                        },
+                    };
+                }
+            },
+            // `didWriteRecommendations` is false on the skip paths, which resolve
+            // the status without fetching anything. Consumers that react by
+            // recomputing local state must not run then — there is nothing new to
+            // apply, and recomputing would reset the line's "update to" selections.
+            prepare(billId, didWriteRecommendations = false) {
+                return {
+                    payload: { billId, didWriteRecommendations },
+                };
+            },
+        },
+        fetchBillRecommendationsFailure: {
+            reducer(draft, action) {
+                const key = getBillTransactionDetailKey(action.payload.billId);
+                const detail = recordGet(draft.billDetailById, key, undefined);
+                if (detail != null) {
+                    draft.billDetailById[key] = {
+                        ...detail,
+                        recommendationsFetchStatus: {
+                            fetchState: 'Error',
+                            error: action.payload.error,
+                        },
+                    };
+                }
+            },
+            prepare(billId, error) {
+                return {
+                    payload: { billId, error },
+                };
+            },
+        },
         deleteBill: {
             reducer(draft, action) {
                 const key = getBillTransactionDetailKey(action.payload.billId);
@@ -462,5 +548,5 @@ const billDetailView = createSlice({
         });
     },
 });
-export const { fetchBillDetail, updateBillDetail, updateBillDetailFetchState, removeBillDetail, deleteBill, deleteBillSuccessOrFailure, approveOrRejectBill, approveOrRejectBillSuccess, approveOrRejectBillFailure, updateApprovalStatusOnSuccess, cancelAndDeleteBill, cancelAndDeleteBillSuccessOrFailure, waitForVendorByNameThenUpdateBillDetail, fetchEligibleActionsForBill, updateEligibleActionsForBill, updateFetchEligibleActionsFailureState, retryOrRefundBill, retryOrRefundBillSuccess, retryOrRefundBillFailure, } = billDetailView.actions;
+export const { fetchBillDetail, fetchBillRecommendations, fetchBillRecommendationsSuccess, fetchBillRecommendationsFailure, updateBillDetail, updateBillDetailFetchState, removeBillDetail, deleteBill, deleteBillSuccessOrFailure, approveOrRejectBill, approveOrRejectBillSuccess, approveOrRejectBillFailure, updateApprovalStatusOnSuccess, cancelAndDeleteBill, cancelAndDeleteBillSuccessOrFailure, waitForVendorByNameThenUpdateBillDetail, fetchEligibleActionsForBill, updateEligibleActionsForBill, updateFetchEligibleActionsFailureState, retryOrRefundBill, retryOrRefundBillSuccess, retryOrRefundBillFailure, } = billDetailView.actions;
 export default billDetailView.reducer;

package/lib/esm/view/spendManagement/billPay/billDetailView/billDetailViewSelector.js

@@ -219,6 +219,7 @@ export const getBillDetailView = (state, billId) => {
         fetchState: fetchState.fetchState,
         error: fetchState.error,
         version: 0,
+        recommendationsFetchStatus: billTransactionDetails?.recommendationsFetchStatus,
         transactionDetails: transaction,
         createdBy,
         bankAccount,

package/lib/esm/view/spendManagement/billPay/billDetailView/billDetailViewState.js

@@ -30,6 +30,10 @@ export const initialBillDetailView = {
         fetchState: 'Not-Started',
         error: undefined,
     },
+    recommendationsFetchStatus: {
+        fetchState: 'Not-Started',
+        error: undefined,
+    },
     billId: undefined,
     eventIds: [],
     entityApprovalIds: [],

package/lib/esm/view/spendManagement/billPay/billDetailView/epics/fetchBillRecommendationsEpic.js

@@ -0,0 +1,97 @@
+import recordGet from 'lodash/get';
+import { of } from 'rxjs';
+import { exhaustMap, filter, groupBy, mergeMap, take } from 'rxjs/operators';
+import { createZeniAPIStatus } from '../../../../../responsePayload';
+import { fetchBillRecommendations, fetchBillRecommendationsFailure, updateBillDetail, updateBillDetailFetchState, } from '../billDetailViewReducer';
+import { getBillTransactionDetailKey } from '../billDetailViewState';
+import { fetchRecommendationsForBill, getBillTransaction, } from './fetchRecommendationsForBill';
+/**
+ * Standalone recommendations fetch for a bill, so neither the bill detail nor
+ * the bill edit screen waits on recommendation composition.
+ *
+ * Which bills need it is decided from the bill's stage: an approval-stage bill
+ * gets them from the dedicated endpoint
+ * (`GET /1.0/bills/transactions/{transaction_id}/recommendations`), while a
+ * draft gets them on the bill detail response itself. The platform makes that
+ * split from the bill's status, so neither request carries a flag asking for
+ * one behaviour or the other.
+ *
+ * Only `recommendations` is read — per line, and what drives the "Update to X"
+ * checkbox and the Recommended group in the category/class dropdowns. The
+ * endpoint returns no entity-level recommendation and the edit form does not
+ * render one.
+ *
+ * Failure is confined to `recommendationsFetchStatus` — no bill-detail action
+ * is emitted, so a failed or slow recommendations fetch can neither block nor
+ * error out either screen.
+ *
+ * @precondition Every site dispatching `fetchBillRecommendations` must also
+ * cause the bill detail to be requested for that bill. This epic waits for the
+ * detail when it is not already in the store, and that wait settles only on a
+ * detail write or a detail error. A caller that dispatches without one would
+ * leave the wait open, and the per-bill `exhaustMap` would then drop later
+ * retries for that bill. Both current callers satisfy this: the bill detail
+ * route dispatches `fetchBillDetail` alongside, and the edit route reaches it
+ * through `fetchEditBillDetailPage`.
+ */
+export const fetchBillRecommendationsEpic = (actions$, state$, zeniAPI) => actions$.pipe(filter(fetchBillRecommendations.match), 
+// The bill detail route requests these and the edit screen asks again on
+// every mount, so repeats are normal. Drop the ones whose bill is already
+// done before they reach the request.
+filter((action) => action.payload.cacheOverride === true ||
+    areRecommendationsAlreadyFetched(state$.value, action.payload.billId) === false), 
+// Per bill, then `exhaustMap` rather than `switchMap`: a repeat that
+// arrives while the request (or the wait for the bill detail) is still
+// running is ignored, where `switchMap` would cancel the in-flight one and
+// re-issue it. `groupBy` keeps that per bill, so navigating to another
+// bill mid-flight still fetches for the new one.
+groupBy((action) => action.payload.billId), mergeMap((actionsForBill$) => actionsForBill$.pipe(exhaustMap((action) => {
+    const { billId, cacheOverride } = action.payload;
+    if (isBillReadyForRecommendations(state$.value, billId)) {
+        return fetchRecommendationsForBill(state$.value, billId, zeniAPI, cacheOverride);
+    }
+    // The edit route can mount before the bill detail response lands,
+    // and the request needs the vendor / line ids / amount from it. Wait
+    // for the detail write for this bill rather than dropping the fetch,
+    // and settle on a detail error too.
+    //
+    // A leftover `Error` on the bill detail is deliberately NOT treated
+    // as terminal here. On the edit route this action is dispatched
+    // before the parent screen re-requests the detail — React runs the
+    // child's effect first — so failing on the stale error would leave
+    // recommendations failed even though the detail is about to succeed.
+    //
+    // The invariant this relies on: every dispatch site also causes the
+    // bill detail to be requested. Both do today. A future site that
+    // does not would leave this waiting, and `exhaustMap` would drop
+    // later retries for that bill.
+    const billDetailSettled$ = actions$.pipe(filter((waited) => {
+        if (updateBillDetail.match(waited)) {
+            return waited.payload.billId === billId;
+        }
+        return (updateBillDetailFetchState.match(waited) &&
+            waited.payload.fetchState === 'Error' &&
+            waited.payload.billId === billId);
+    }), take(1) // don't listen forever! IMPORTANT!
+    );
+    return billDetailSettled$.pipe(mergeMap((waited) => {
+        if (updateBillDetail.match(waited)) {
+            return fetchRecommendationsForBill(state$.value, billId, zeniAPI, cacheOverride);
+        }
+        // Bill detail failed; there is nothing to recommend against.
+        return of(fetchBillRecommendationsFailure(billId, waited.payload.error ??
+            createZeniAPIStatus('Unexpected Error', 'Bill detail fetch failed before recommendations could be requested')));
+    }));
+}))));
+/**
+ * Helper functions
+ */
+function areRecommendationsAlreadyFetched(state, billId) {
+    const billDetail = recordGet(state.billDetailViewState.billDetailById, getBillTransactionDetailKey(billId), undefined);
+    return billDetail?.recommendationsFetchStatus.fetchState === 'Completed';
+}
+function isBillReadyForRecommendations(state, billId) {
+    const billDetail = recordGet(state.billDetailViewState.billDetailById, getBillTransactionDetailKey(billId), undefined);
+    return (billDetail?.fetchState === 'Completed' &&
+        getBillTransaction(state, billId) != null);
+}

package/lib/esm/view/spendManagement/billPay/billDetailView/epics/fetchRecommendationsForBill.js

@@ -0,0 +1,85 @@
+import recordGet from 'lodash/get';
+import { from, of } from 'rxjs';
+import { catchError, mergeMap } from 'rxjs/operators';
+import { transformRecommendation } from '../../../../../commonPayloadTypes/recommendationPayload';
+import { updateBillTransactionRecommendations } from '../../../../../entity/billPay/billTransaction/billTransactionReducer';
+import { createZeniAPIStatus, isSuccessResponse, } from '../../../../../responsePayload';
+import { fetchBillRecommendationsFailure, fetchBillRecommendationsSuccess, } from '../billDetailViewReducer';
+/**
+ * Requests the recommendations for one bill and maps them onto the transaction
+ * entity, or resolves without a request for a bill that does not need them.
+ *
+ * Only `recommendations` is read from the response — per line, and what drives
+ * the "Update to X" checkbox and the Recommended group in the category/class
+ * dropdowns. The endpoint returns no entity-level recommendation and the edit
+ * form does not render one.
+ */
+export function fetchRecommendationsForBill(state, billId, zeniAPI, cacheOverride = false) {
+    const transaction = getBillTransaction(state, billId);
+    const lineIds = transaction?.lines?.map((line) => line.id) ?? [];
+    if (transaction == null ||
+        shouldSkipRecommendations(transaction, cacheOverride)) {
+        return of(fetchBillRecommendationsSuccess(billId));
+    }
+    // The bill is scoped by the path, so this endpoint takes no query — there is
+    // no `is_include_*` flag to turn off the way the bill detail request has.
+    return zeniAPI
+        .getJSON(`${zeniAPI.apiEndPoints.spendManagementMicroServiceBaseUrl}/1.0/bills/transactions/${billId}/recommendations`)
+        .pipe(mergeMap((response) => {
+        if (!isSuccessResponse(response) || response.data == null) {
+            return of(fetchBillRecommendationsFailure(billId, response.status));
+        }
+        const actions = [];
+        // Positional line <-> recommendation mapping, matching
+        // `getRecommendationsPerLine` — the mapping the recommendations went
+        // through while the bill detail response still carried them. This
+        // endpoint returns them flat, not nested under `transaction`.
+        const recommendationPayloads = response.data.recommendations ?? [];
+        // The pairing is a convention shared with the platform, not
+        // something the payload enforces, so a mismatch would otherwise
+        // mis-assign or silently drop recommendations. Degrade safely —
+        // extra entries are ignored and unmatched lines get none — but say
+        // so, because it means the two sides have diverged.
+        if (recommendationPayloads.length !== lineIds.length) {
+            console.warn(`Bill ${billId}: ${recommendationPayloads.length} recommendation entries for ${lineIds.length} lines. ` +
+                'They are paired by position, so this bill may be scored incorrectly.');
+        }
+        const recommendationByLineId = {};
+        lineIds.forEach((lineId, index) => {
+            const recommendationPayload = recommendationPayloads[index];
+            if (recommendationPayload != null) {
+                recommendationByLineId[lineId] = transformRecommendation(recommendationPayload);
+            }
+        });
+        actions.push(updateBillTransactionRecommendations(billId, recommendationByLineId));
+        // Entity writes first, then the view status, so consumers reading on
+        // the status flip already see the recommendations.
+        actions.push(fetchBillRecommendationsSuccess(billId, true));
+        return from(actions);
+    }), catchError((error) => of(fetchBillRecommendationsFailure(billId, createZeniAPIStatus('Unexpected Error', `Fetch bill recommendations REST API call errored out ${error}`)))));
+}
+export function getBillTransaction(state, billId) {
+    return recordGet(state.billTransactionState.transactionById, billId, undefined);
+}
+/**
+ * Helper functions
+ */
+// Awaiting-approval bills are the only ones this request exists for. A draft
+// opens the edit form directly, so its recommendations ride along on the bill
+// detail response; `paid` bills cannot reach the form at all. The platform
+// decides which of those two it is from the bill's status, which is why the
+// request carries no flag asking for either.
+function shouldSkipRecommendations(transaction, cacheOverride) {
+    return (transaction.billPayInfo.stage.code !== 'pending_approval' ||
+        transaction.isDeleted === true ||
+        // No vendor (a draft carrying only a candidate vendor name) means no
+        // entity to recommend against — the vendor-selection flow covers that.
+        Boolean(transaction.vendor?.id) === false ||
+        // The bill detail response already carried them. `toVendorTransaction`
+        // maps them straight onto the entity, so requesting again would only
+        // re-fetch what is here — this is what lets the platform move the line
+        // between embedded and on-demand without a client change. A forced
+        // refresh is the one case that still goes to the endpoint.
+        (cacheOverride === false &&
+            Object.keys(transaction.recommendations ?? {}).length > 0));
+}

package/lib/esm/view/spendManagement/billPay/editBillView/editBillViewReducer.js

@@ -149,6 +149,23 @@ const editBillView = createSlice({
                 }
             }
         },
+        // Applied when the standalone recommendations fetch resolves after the
+        // edit local store was already initialized. `initializeBillToLocalStore`
+        // is guarded to run once, so without this the late recommendations would
+        // never reach the category/class autofill or the "update to" checkbox.
+        updateBillLineRecommendationsInLocalStore: {
+            reducer(draft, action) {
+                const { billId, updatesByLineId } = action.payload;
+                const key = getBillTransactionDetailKey(billId);
+                const editBill = draft.editBillStateById[key];
+                if (editBill != null) {
+                    editBill.billDetailLocalData.updatesByLineId = Object.assign({}, editBill.billDetailLocalData.updatesByLineId, updatesByLineId);
+                }
+            },
+            prepare(billId, updatesByLineId) {
+                return { payload: { billId, updatesByLineId } };
+            },
+        },
         discardBillUpdatesInLocalStore(draft, action) {
             if (action.payload.billId != null) {
                 const { billId } = action.payload;
@@ -494,7 +511,7 @@ const editBillView = createSlice({
         });
     },
 });
-export const { fetchEditBillDetailPage, fetchBillAndInitializeLocalStore, fetchVendorByNameAndParseInvoice, initializeBillToLocalStore, saveBillUpdatesToLocalStore, discardBillUpdatesInLocalStore, saveBillDetail, saveBillSuccessOrFailure, updateEditBillFetchStateCompleted, parseInvoiceToBill, waitForBillDetailThenInitializeLocalStore, waitForVendorByNameThenParsetoLocalStore, updateInternationalTransferFeeBearerPaymentMethodInLocalData, updateShowAutofill, updateAddBillAutoFields, updateBillUploadFetchState, updateRecommendedVendorId, updateSuggestedVendorIdFromParsedInvoice, updateVendorContact, updateVendorContactSuccessOrFailure, convertAmountToHomeCurrency, currencyConversionValueSuccessOrFailure, updateHomeCurrencyConversion, fetchVendorAndUpdateBillLocalData, waitForVendorByIdThenSaveBillUpdatetoLocalStore, markBillForRetry, updateOutsideZeniPaymentLocalData, discardOutsideZeniPaymentLocalData, updateNewAddedBillPaymentAccount, updateWithdrawFromAccountId, removeBillFileFromLocalStore, replaceBillFileInLocalStore, updateShouldReplaceBillData, } = editBillView.actions;
+export const { fetchEditBillDetailPage, fetchBillAndInitializeLocalStore, fetchVendorByNameAndParseInvoice, initializeBillToLocalStore, saveBillUpdatesToLocalStore, updateBillLineRecommendationsInLocalStore, discardBillUpdatesInLocalStore, saveBillDetail, saveBillSuccessOrFailure, updateEditBillFetchStateCompleted, parseInvoiceToBill, waitForBillDetailThenInitializeLocalStore, waitForVendorByNameThenParsetoLocalStore, updateInternationalTransferFeeBearerPaymentMethodInLocalData, updateShowAutofill, updateAddBillAutoFields, updateBillUploadFetchState, updateRecommendedVendorId, updateSuggestedVendorIdFromParsedInvoice, updateVendorContact, updateVendorContactSuccessOrFailure, convertAmountToHomeCurrency, currencyConversionValueSuccessOrFailure, updateHomeCurrencyConversion, fetchVendorAndUpdateBillLocalData, waitForVendorByIdThenSaveBillUpdatetoLocalStore, markBillForRetry, updateOutsideZeniPaymentLocalData, discardOutsideZeniPaymentLocalData, updateNewAddedBillPaymentAccount, updateWithdrawFromAccountId, removeBillFileFromLocalStore, replaceBillFileInLocalStore, updateShouldReplaceBillData, } = editBillView.actions;
 export default editBillView.reducer;
 function doUpdateRecurringBillLocalData(billDetail, currentConfig, prevConfig) {
     const recurringBillDetail = updateRecurringBillDetails(currentConfig, prevConfig, billDetail.recurringBillInstances, billDetail.recipientTotalAmount?.amount);

package/lib/esm/view/spendManagement/billPay/editBillView/editBillViewSelector.js

@@ -380,6 +380,9 @@ export const getEditBillDetail = (state, isVendorRecommendationFeatureEnabled, i
         classHierarchyList,
         latestApprovedDate: getLatestApprovalDate(billActivities),
         recommendationByLineID: recommendations,
+        recommendationsFetchStatus: billId != null
+            ? billDetailViewState.billDetailById[getBillTransactionDetailKey(billId)]?.recommendationsFetchStatus
+            : undefined,
         isRecurring,
         recurringBillInstances,
         recurringConfig,

package/lib/esm/view/spendManagement/billPay/editBillView/epics/applyBillRecommendationsToLocalStoreEpic.js

@@ -0,0 +1,95 @@
+import recordGet from 'lodash/get';
+import { EMPTY, of } from 'rxjs';
+import { filter, mergeMap } from 'rxjs/operators';
+import { getAccountList, } from '../../../../accountList/accountListSelector';
+import { getClassList, } from '../../../../classList/classListSelector';
+import { fetchBillRecommendationsSuccess } from '../../billDetailView/billDetailViewReducer';
+import { getBillTransactionDetailKey } from '../../billDetailView/billDetailViewState';
+import { updateBillLineRecommendationsInLocalStore } from '../editBillViewReducer';
+import { getLineRecommendationsLocalData } from './initializeBillToLocalStoreEpic';
+/**
+ * Back-fills the edit local store once the standalone recommendations fetch
+ * resolves. `initializeBillToLocalStore` reads `transaction.recommendations`
+ * exactly once and is guarded against re-running, so the recommendation-derived
+ * line data (category/class autofill, `recommendedCategory` / `recommendedClass`
+ * behind the "update to" checkbox) has to be recomputed here instead.
+ *
+ * Recomputes from the entity lines with the same helper the initializer uses, so
+ * an untouched line ends up exactly as it would have had the recommendations
+ * been present at init time.
+ */
+export const applyBillRecommendationsToLocalStoreEpic = (actions$, state$) => actions$.pipe(filter(fetchBillRecommendationsSuccess.match), 
+// The skip paths resolve the status without fetching — a draft whose
+// recommendations came on the bill detail response, or a stage that is not
+// served any. `initializeBillToLocalStore` has already read those, so
+// recomputing here would only reset the line's "update to" selections.
+filter((action) => action.payload.didWriteRecommendations), mergeMap((action) => {
+    const { billId } = action.payload;
+    const state = state$.value;
+    const key = getBillTransactionDetailKey(billId);
+    const editBillState = recordGet(state.editBillDetailViewState.editBillStateById, key, undefined);
+    const transaction = recordGet(state.billTransactionState.transactionById, billId, undefined);
+    const recommendations = transaction?.recommendations;
+    if (editBillState == null ||
+        transaction == null ||
+        transaction.lines == null ||
+        recommendations == null ||
+        Object.keys(recommendations).length === 0) {
+        return EMPTY;
+    }
+    const localData = editBillState.billDetailLocalData;
+    // The recommendations were requested for the vendor on the bill. If the
+    // user has since switched vendors, `fetchVendorAndUpdateBillLocalData`
+    // owns the line data and these are stale — leave it alone.
+    //
+    // Both sides are QBO ids despite the field names suggesting otherwise.
+    // `transaction.vendor` is built by `mapVendorBasePayloadToVendorBase`,
+    // whose id is `getVendorPayloadIdentifier` = `vendor_id ?? qbo_id`, and
+    // on a bill transaction payload `vendor_id` IS the QBO id — the Zeni id
+    // rides separately as `zeni_vendor_id`. Verified against live DEV and QA
+    // responses, both of which have `vendor_id === qbo_vendor_id`.
+    if (localData.vendor?.qboId !== transaction.vendor?.id) {
+        return EMPTY;
+    }
+    const accountList = getAccountList(state.accountState, state.accountListState, 'billPayAccountList');
+    const classList = getClassList(state.classState, state.classListState);
+    const updatesByLineId = {};
+    transaction.lines.forEach((line) => {
+        // A line whose category/class the user already set keeps their input.
+        const localLine = localData.updatesByLineId[line.id];
+        if (localLine?.isCategoryOrClassUpdated) {
+            return;
+        }
+        // The helper spreads whatever line it is given into its result, and
+        // the reducer replaces the entry wholesale, so the local line has to
+        // go in or edits that leave `isCategoryOrClassUpdated` untouched — an
+        // amount or description changed while this fetch was in flight — get
+        // reverted.
+        //
+        // Category and class are the exception and come from the ENTITY line,
+        // exactly as at init. By now the local line may hold a category the
+        // vendor default autofilled when no recommendation was available yet,
+        // and the helper reads whatever it is given as the line's original
+        // value and will not replace one. Passing that back would leave an
+        // untouched line on the vendor default instead of the per-line
+        // recommendation, so the back-fill would not match what init would
+        // have produced had the recommendations been there all along.
+        const localLineWithEntityCategory = localLine == null || hasAccountAndClass(line) === false
+            ? line
+            : {
+                ...localLine,
+                account: line.account,
+                class: line.class,
+            };
+        updatesByLineId[line.id] = getLineRecommendationsLocalData(line.id, localLineWithEntityCategory, recommendations, accountList, classList, localData.vendor);
+    });
+    if (Object.keys(updatesByLineId).length === 0) {
+        return EMPTY;
+    }
+    return of(updateBillLineRecommendationsInLocalStore(billId, updatesByLineId));
+}));
+// Only some `Line` members carry a category and class. A guard rather than a
+// cast so a shape change is a compile error, not a silent `undefined`.
+function hasAccountAndClass(line) {
+    return 'account' in line;
+}