@zeniai/client-epic-state 5.1.7 → 5.1.8

package/lib/esm/view/spendManagement/cashManagement/autoSweepFlow/autoSweepFlowReducer.js

@@ -0,0 +1,78 @@
+import { createSlice } from '@reduxjs/toolkit';
+import { toAutoSweepFlowStatePatch, } from './autoSweepFlowPayload';
+import { initialAutoSweepFlowState, } from './autoSweepFlowState';
+export const initialState = initialAutoSweepFlowState;
+const autoSweepFlow = createSlice({
+    name: 'autoSweepFlow',
+    initialState,
+    reducers: {
+        /**
+         * Kicks off `GET /cash-management/settings`. Flips the top-level
+         * fetchState to `In-Progress`; the fetch epic picks this up.
+         */
+        fetchCashManagementSettings(draft) {
+            draft.fetchState = 'In-Progress';
+            draft.error = undefined;
+        },
+        /**
+         * Hydrates the form fields with the server-side settings (and stashes
+         * the settings id for subsequent saves). Marks the GET as `Completed`.
+         */
+        updateCashManagementSettings(draft, action) {
+            const patch = toAutoSweepFlowStatePatch(action.payload.data);
+            draft.bufferAmount = patch.bufferAmount;
+            draft.frequency = patch.frequency;
+            draft.nextTransferDate = patch.nextTransferDate;
+            draft.primaryFundingAccountId = patch.primaryFundingAccountId;
+            draft.settingsId = patch.settingsId;
+            draft.fetchState = 'Completed';
+            draft.error = undefined;
+        },
+        updateCashManagementSettingsFetchStatus(draft, action) {
+            draft.fetchState = action.payload.fetchState;
+            draft.error = action.payload.error;
+        },
+        /**
+         * Live-update the buffer (risk band) as the user toggles the risk picker
+         * on the setup page, without staging frequency/memo. The selector derives
+         * the risk-adjusted sweep amount off `bufferAmount`, so dispatching this on
+         * every risk change keeps the setup and review screens in sync.
+         */
+        updateAutoSweepRisk(draft, action) {
+            draft.bufferAmount = action.payload.bufferAmount;
+        },
+        /**
+         * Stage the in-flight form values without submitting them — fired from
+         * the setup→review transition so other selectors (and devtools) can see
+         * what the user is about to confirm. Leaves `saveStatus` untouched; the
+         * actual PUT only kicks off when the user clicks "Confirm Sweep" via
+         * `saveAutoSweepSettings`.
+         */
+        updateAutoSweepDraft(draft, action) {
+            draft.bufferAmount = action.payload.bufferAmount;
+            draft.frequency = action.payload.frequency;
+            draft.memo = action.payload.memo;
+        },
+        /**
+         * Trigger the PUT for the auto-sweep settings already staged via
+         * `updateAutoSweepDraft`. Carries no payload — flips `saveStatus` to
+         * `In-Progress` and the save epic reads `bufferAmount` / `frequency` /
+         * `memo` straight from the slice. Callers must ensure those fields
+         * reflect the user's latest input before dispatching.
+         */
+        saveAutoSweepSettings(draft) {
+            draft.saveStatus = { fetchState: 'In-Progress', error: undefined };
+        },
+        updateAutoSweepSettingsFetchStatus(draft, action) {
+            draft.saveStatus = {
+                fetchState: action.payload.fetchState,
+                error: action.payload.error,
+            };
+        },
+        clearAutoSweepFlow() {
+            return initialAutoSweepFlowState;
+        },
+    },
+});
+export const { fetchCashManagementSettings, updateCashManagementSettings, updateCashManagementSettingsFetchStatus, updateAutoSweepRisk, updateAutoSweepDraft, saveAutoSweepSettings, updateAutoSweepSettingsFetchStatus, clearAutoSweepFlow, } = autoSweepFlow.actions;
+export default autoSweepFlow.reducer;

package/lib/esm/view/spendManagement/cashManagement/autoSweepFlow/autoSweepFlowSelector.js

@@ -0,0 +1,49 @@
+import { getDepositAccountByDepositAccountId } from '../../../../entity/depositAccount/depositAccountSelector';
+import { mapDepositAccToFundingAccount, } from '../../commonSetup/setupViewSelector';
+import { getTreasuryDetail } from '../../treasury/treasuryList/treasuryDetailSelector';
+import { getCashManagementOverviewBanner } from '../cashManagementOverview/cashManagementOverviewSelector';
+import { RISK_BUFFER_AMOUNT, bufferAmountToRisk, } from './autoSweepFlowState';
+/**
+ * Risk band the agent's recommended sweep amount is computed against. The
+ * `sweepAmount` returned by the banner assumes this buffer, so the selector
+ * adjusts the displayed sweep by the delta between the user's selected band
+ * and this default.
+ */
+const DEFAULT_RISK_LEVEL = 'moderate';
+export const getAutoSweepFlow = (state) => {
+    const { bufferAmount, frequency, memo, saveStatus, settingsId, primaryFundingAccountId, fetchState, error, } = state.autoSweepFlowState;
+    const depositAccount = primaryFundingAccountId != null
+        ? getDepositAccountByDepositAccountId(state.depositAccountState, primaryFundingAccountId)
+        : undefined;
+    const risk = bufferAmountToRisk(bufferAmount.amount);
+    // The banner's recommended sweep assumes the default buffer band; shift it
+    // by the delta between the default buffer and the user's selected band so a
+    // tighter buffer (higher risk → smaller buffer) sweeps more and a looser
+    // buffer (lower risk → larger buffer) sweeps less. Clamp at zero so a buffer
+    // larger than the available surplus never yields a negative sweep.
+    const baseSweepAmount = getCashManagementOverviewBanner(state).amount;
+    const sweepAmount = {
+        ...baseSweepAmount,
+        amount: Math.max(0, baseSweepAmount.amount +
+            RISK_BUFFER_AMOUNT[DEFAULT_RISK_LEVEL] -
+            RISK_BUFFER_AMOUNT[risk]),
+    };
+    return {
+        fetchState,
+        error,
+        formData: {
+            bufferAmount,
+            frequency,
+            memo,
+            risk,
+        },
+        primaryFundingAccount: depositAccount != null
+            ? mapDepositAccToFundingAccount(depositAccount)
+            : undefined,
+        saveStatus,
+        settingsId,
+        sweepAmount,
+        treasurySummary: getTreasuryDetail(state).accountSummary,
+        version: 0,
+    };
+};

package/lib/esm/view/spendManagement/cashManagement/autoSweepFlow/autoSweepFlowState.js

@@ -0,0 +1,47 @@
+import { toAmount } from '../../../../commonStateTypes/amount';
+import { stringToUnion } from '../../../../commonStateTypes/stringToUnion';
+/**
+ * Cadence at which the auto-sweep transfer fires. Lowercase to match the
+ * cash-management settings API contract (and the `SweepFrequency` literal
+ * already used by `<AutoSweepSetupPage>` in web-components).
+ */
+export const ALL_AUTO_SWEEP_FREQUENCIES = [
+    'daily',
+    'weekly',
+    'biweekly',
+    'monthly',
+];
+export const toAutoSweepFrequency = (v) => stringToUnion(v ?? '', ALL_AUTO_SWEEP_FREQUENCIES);
+/**
+ * Risk presets the auto-sweep setup form exposes. Each level maps to a
+ * canonical minimum-buffer amount (USD). Selecting a level in the UI is
+ * shorthand for choosing that buffer.
+ */
+export const ALL_AUTO_SWEEP_RISK_LEVELS = ['low', 'moderate', 'high'];
+export const toAutoSweepRiskLevel = (v) => stringToUnion(v ?? '', ALL_AUTO_SWEEP_RISK_LEVELS);
+export const RISK_BUFFER_AMOUNT = {
+    low: 15000,
+    moderate: 10000,
+    high: 5000,
+};
+/**
+ * Maps a buffer amount back onto the closest preset risk level. Falls back
+ * to `'moderate'` when the amount doesn't match a known preset (e.g. the
+ * server returned a custom value). The dropdown in `<AutoSweepSetupPage>`
+ * uses this so it can pre-select the user's existing band on edit.
+ */
+export const bufferAmountToRisk = (amount) => {
+    const match = Object.entries(RISK_BUFFER_AMOUNT).find(([, presetAmount]) => presetAmount === amount);
+    return match != null ? match[0] : 'moderate';
+};
+export const initialAutoSweepFlowState = {
+    bufferAmount: toAmount(10000, 'USD', '$'),
+    frequency: 'weekly',
+    memo: '',
+    saveStatus: { fetchState: 'Not-Started', error: undefined },
+    nextTransferDate: undefined,
+    primaryFundingAccountId: undefined,
+    settingsId: undefined,
+    fetchState: 'Not-Started',
+    error: undefined,
+};

package/lib/esm/view/spendManagement/cashManagement/autoSweepFlow/epics/fetchCashManagementSettingsEpic.js

@@ -0,0 +1,32 @@
+import { of } from 'rxjs';
+import { catchError, filter, mergeMap, switchMap } from 'rxjs/operators';
+import { updateDepositAccounts } from '../../../../../entity/depositAccount/depositAccountReducer';
+import { createZeniAPIStatus, isSuccessResponse, } from '../../../../../responsePayload';
+import { fetchCashManagementSettings, updateCashManagementSettings, updateCashManagementSettingsFetchStatus, } from '../autoSweepFlowReducer';
+/**
+ * Hits `GET /cash-management/settings` and hydrates the auto-sweep slice
+ * with the server's existing settings (frequency, minimum buffer, settings
+ * id). Called from the cash management overview page-fetch epic alongside
+ * the other top-level fetches.
+ */
+export const fetchCashManagementSettingsEpic = (actions$, _state$, zeniAPI) => actions$.pipe(filter(fetchCashManagementSettings.match), switchMap(() => {
+    const endpoint = `${zeniAPI.apiEndPoints.cashManagementAgentBaseUrl}/1.0/cash-management/settings`;
+    return zeniAPI.getJSON(endpoint).pipe(mergeMap((response) => {
+        if (isSuccessResponse(response) && response.data != null) {
+            return of(
+            // Publish the source deposit account into the shared entity
+            // bucket so the selector can hydrate the full `FundingAccount`
+            // from `getDepositAccountByDepositAccountId` rather than the
+            // auto-sweep slice holding a duplicate copy.
+            updateDepositAccounts([response.data.source_bank_account]), updateCashManagementSettings({ data: response.data }));
+        }
+        return of(updateCashManagementSettingsFetchStatus({
+            fetchState: 'Error',
+            error: response.status,
+        }));
+    }), catchError((error) => of(updateCashManagementSettingsFetchStatus({
+        fetchState: 'Error',
+        error: createZeniAPIStatus('Unexpected Error', 'Fetch cash management settings REST API call errored out: ' +
+            (error?.message ?? String(error))),
+    }))));
+}));

package/lib/esm/view/spendManagement/cashManagement/autoSweepFlow/epics/saveAutoSweepSettingsEpic.js

@@ -0,0 +1,32 @@
+import { of } from 'rxjs';
+import { catchError, filter, mergeMap, switchMap } from 'rxjs/operators';
+import { createZeniAPIStatus, isSuccessResponse, } from '../../../../../responsePayload';
+import { toSaveAutoSweepSettingsBody, } from '../autoSweepFlowPayload';
+import { saveAutoSweepSettings, updateAutoSweepSettingsFetchStatus, } from '../autoSweepFlowReducer';
+export const saveAutoSweepSettingsEpic = (actions$, state$, zeniAPI) => actions$.pipe(filter(saveAutoSweepSettings.match), switchMap(() => {
+    const endpoint = `${zeniAPI.apiEndPoints.cashManagementAgentBaseUrl}/1.0/cash-management/settings`;
+    const { bufferAmount, frequency, memo, settingsId } = state$.value.autoSweepFlowState;
+    const payload = toSaveAutoSweepSettingsBody({
+        bufferAmount,
+        frequency,
+        memo,
+    });
+    // First-time setup (no settings id from the GET yet) → POST a new
+    // record. Subsequent edits update the existing one via PUT.
+    const request$ = settingsId == null
+        ? zeniAPI.postAndGetJSON(endpoint, payload)
+        : zeniAPI.putAndGetJSON(endpoint, payload);
+    return request$.pipe(mergeMap((response) => {
+        if (isSuccessResponse(response) && response.data != null) {
+            return of(updateAutoSweepSettingsFetchStatus({ fetchState: 'Completed' }));
+        }
+        return of(updateAutoSweepSettingsFetchStatus({
+            fetchState: 'Error',
+            error: response?.status,
+        }));
+    }), catchError((error) => of(updateAutoSweepSettingsFetchStatus({
+        fetchState: 'Error',
+        error: createZeniAPIStatus('Unexpected Error', 'Save auto-sweep settings REST API call errored out: ' +
+            (error?.message ?? String(error))),
+    }))));
+}));

package/lib/esm/view/spendManagement/cashManagement/cashManagementOverview/cashManagementOverviewPayload.js

@@ -0,0 +1,54 @@
+import { toAmount } from '../../../../commonStateTypes/amount';
+import { date as zeniDate } from '../../../../zeniDayJS';
+// ---------------------------------------------------------------------------
+// Converters
+// ---------------------------------------------------------------------------
+// The cash agent payload reports `currency_code` only; the v1 surface is
+// USD-only, so we pair it with the canonical `$` symbol here. If the agent
+// grows multi-currency support, this is the single place to widen.
+const CASH_AGENT_CURRENCY_SYMBOL = '$';
+export const toUpcomingPaymentEvent = (event) => ({
+    accountId: event.account_id,
+    accountType: event.account_type,
+    amount: toAmount(event.amount_usd, event.currency_code, CASH_AGENT_CURRENCY_SYMBOL),
+    label: event.label,
+    paymentDate: zeniDate(event.payment_date),
+});
+/**
+ * The agent reports a `null` account id whenever the "account" in question is
+ * a singleton inferred from the account type (today: the treasury account —
+ * there's only one per company, so the type alone identifies it). Callers
+ * already branch on `*BankAccountType`, so collapsing the id to `""` keeps the
+ * state type a plain `ID` (string) without losing information.
+ */
+const toCashManagementMovement = (payload) => ({
+    amount: toAmount(payload.amount, payload.currency_code, CASH_AGENT_CURRENCY_SYMBOL),
+    destinationBankAccountId: payload.destination_bank_account_id ?? '',
+    destinationBankAccountType: payload.destination_bank_account_type,
+    reasoning: payload.reasoning,
+    sourceBankAccountId: payload.source_bank_account_id ?? '',
+    sourceBankAccountType: payload.source_bank_account_type,
+    subMovementType: payload.sub_movement_type,
+});
+const toCashManagementMoneyMovementGroup = (payload) => ({
+    movements: payload.movements.map(toCashManagementMovement),
+    movementType: payload.movement_type,
+});
+export const toCashManagementBannerData = (payload) => ({
+    inflows: payload.inflows.map(toUpcomingPaymentEvent),
+    moneyMovements: payload.money_movements.map(toCashManagementMoneyMovementGroup),
+    outflows: payload.outflows.map(toUpcomingPaymentEvent),
+});
+export const toCashManagementTransfer = (payload) => ({
+    amount: toAmount(payload.amount, payload.currency_code, CASH_AGENT_CURRENCY_SYMBOL),
+    atomicTransactionId: payload.atomic_transaction_id,
+    cashManagementTransferId: payload.cash_management_transfer_id,
+    createTime: zeniDate(payload.create_time),
+    date: zeniDate(payload.date),
+    depositAccountId: payload.deposit_account_id,
+    reasoning: payload.reasoning,
+    scenario: payload.scenario,
+    status: payload.status,
+    transactionType: payload.transaction_type,
+    updateTime: zeniDate(payload.update_time),
+});

package/lib/esm/view/spendManagement/cashManagement/cashManagementOverview/cashManagementOverviewReducer.js

@@ -0,0 +1,92 @@
+import { createSlice } from '@reduxjs/toolkit';
+import { toCashManagementBannerData, toCashManagementTransfer, } from './cashManagementOverviewPayload';
+import { initialCashManagementBannerState, initialCashManagementRecentTransferState, } from './cashManagementOverviewState';
+export const initialState = {
+    banner: initialCashManagementBannerState,
+    recentTransfer: initialCashManagementRecentTransferState,
+};
+const cashManagementOverview = createSlice({
+    name: 'cashManagementOverview',
+    initialState,
+    reducers: {
+        fetchCashManagementOverviewPage: {
+            reducer() { },
+            prepare(cacheOverride) {
+                return { payload: { cacheOverride } };
+            },
+        },
+        /**
+         * Public banner-fetch entry point. Triggers an orchestrator epic that
+         * fans out to the recommend, settings, and recent-transfer API calls
+         * in parallel. No reducer-side state change — each inner action drives
+         * its own sub-state.
+         *
+         * `cacheOverride === true` forces all three inner fetches regardless
+         * of current slice state; `false` keeps the per-slice dedup so repeat
+         * dispatches are no-ops once a slice is loaded or in-flight.
+         */
+        fetchCashManagementBanner: {
+            reducer() { },
+            prepare(cacheOverride) {
+                return { payload: { cacheOverride } };
+            },
+        },
+        /**
+         * Internal trigger for the recommend API (`/cash-agent/recommend`).
+         * Dispatched by the orchestrator; not exported.
+         */
+        fetchCashManagementRecommendation(draft) {
+            // Keep `draft.banner.data` so the projection chart renders the last
+            // good payload while the refetch is in flight, instead of flickering
+            // to the empty/skeleton state on every page revisit.
+            draft.banner.fetchState = 'In-Progress';
+            draft.banner.error = undefined;
+        },
+        updateCashManagementRecommendation(draft, action) {
+            draft.banner = {
+                fetchState: 'Completed',
+                error: undefined,
+                data: toCashManagementBannerData(action.payload.data),
+            };
+        },
+        updateCashManagementRecommendationFetchStatus(draft, action) {
+            draft.banner = {
+                ...draft.banner,
+                fetchState: action.payload.fetchState,
+                error: action.payload.error,
+            };
+        },
+        /**
+         * Internal trigger for the recent-transfer API
+         * (`/cash-management/transfers`). Dispatched by the orchestrator; not
+         * exported.
+         */
+        fetchRecentTransfer(draft) {
+            // Same anti-flicker pattern as the recommend fetch: keep prior data
+            // while the refetch is in flight.
+            draft.recentTransfer.fetchState = 'In-Progress';
+            draft.recentTransfer.error = undefined;
+        },
+        updateRecentTransfer(draft, action) {
+            draft.recentTransfer = {
+                fetchState: 'Completed',
+                error: undefined,
+                data: action.payload.data != null
+                    ? toCashManagementTransfer(action.payload.data)
+                    : undefined,
+            };
+        },
+        updateRecentTransferFetchStatus(draft, action) {
+            draft.recentTransfer = {
+                ...draft.recentTransfer,
+                fetchState: action.payload.fetchState,
+                error: action.payload.error,
+            };
+        },
+        clearCashManagementOverview(draft) {
+            Object.assign(draft, initialState);
+        },
+    },
+});
+export const { fetchCashManagementOverviewPage, fetchCashManagementBanner, fetchCashManagementRecommendation, updateCashManagementRecommendation, updateCashManagementRecommendationFetchStatus, fetchRecentTransfer, updateRecentTransfer, updateRecentTransferFetchStatus, clearCashManagementOverview, } = cashManagementOverview.actions;
+export default cashManagementOverview.reducer;

package/lib/esm/view/spendManagement/cashManagement/cashManagementOverview/cashManagementOverviewSelector.js

@@ -0,0 +1,212 @@
+import { zeroAmount } from '../../../../commonStateTypes/amount';
+import { reduceAllFetchState } from '../../../../commonStateTypes/reduceFetchState';
+import { getDepositAccountByDepositAccountId } from '../../../../entity/depositAccount/depositAccountSelector';
+import { mapDepositAccToFundingAccount, } from '../../commonSetup/setupViewSelector';
+/**
+ * Default account type used when the recommend payload has no movement to
+ * expose yet (e.g. before the first fetch resolves). Callers that care about
+ * the movement should also gate on `fetchState === 'Completed'`.
+ */
+const DEFAULT_BANK_ACCOUNT_TYPE = 'deposit_account';
+const DEFAULT_SUB_MOVEMENT_TYPE = 'push';
+export const getCashManagementOverviewBanner = (state) => {
+    const { banner, recentTransfer } = state.cashManagementOverviewState;
+    const autoSweep = state.autoSweepFlowState;
+    // The banner today surfaces a single recommended movement (the first one
+    // returned by the agent). When the agent returns multiple groups/movements
+    // we'll need to broaden this — for now consumers only render one.
+    const movement = banner.data?.moneyMovements[0]?.movements[0];
+    const aggregate = reduceAllFetchState([
+        { fetchState: banner.fetchState, error: banner.error },
+        { fetchState: autoSweep.fetchState, error: autoSweep.error },
+        { fetchState: recentTransfer.fetchState, error: recentTransfer.error },
+    ]);
+    const subMovementType = movement?.subMovementType ?? DEFAULT_SUB_MOVEMENT_TYPE;
+    // The "primary" account is the deposit-account side of the movement —
+    // source for a push (money leaving primary → treasury) and destination
+    // for a pull (money returning to primary).
+    const primaryAccountId = subMovementType === 'pull'
+        ? movement?.destinationBankAccountId
+        : movement?.sourceBankAccountId;
+    const primaryDepositAccount = primaryAccountId != null && primaryAccountId !== ''
+        ? getDepositAccountByDepositAccountId(state.depositAccountState, primaryAccountId)
+        : undefined;
+    const primaryFundingAccount = primaryDepositAccount != null
+        ? mapDepositAccToFundingAccount(primaryDepositAccount)
+        : undefined;
+    // For pull, surface the largest outflow in the horizon as the
+    // "triggering" event. This is a heuristic — the agent doesn't tag a
+    // specific outflow today, but the largest one is the most likely cause
+    // of the buffer breach and matches what the design wants to highlight.
+    const triggeringOutflow = subMovementType === 'pull'
+        ? pickLargestOutflow(banner.data?.outflows)
+        : undefined;
+    return {
+        fetchState: aggregate.fetchState,
+        error: aggregate.error,
+        amount: movement?.amount ?? zeroAmount(),
+        cashManagementSettingsId: autoSweep.settingsId,
+        destinationBankAccountId: movement?.destinationBankAccountId ?? '',
+        destinationBankAccountType: movement?.destinationBankAccountType ?? DEFAULT_BANK_ACCOUNT_TYPE,
+        reasoning: movement?.reasoning ?? '',
+        sourceBankAccountId: movement?.sourceBankAccountId ?? '',
+        sourceBankAccountType: movement?.sourceBankAccountType ?? DEFAULT_BANK_ACCOUNT_TYPE,
+        subMovementType,
+        primaryFundingAccount,
+        triggeringOutflow,
+        recentTransfer: recentTransfer.data,
+        version: 0,
+    };
+};
+const pickLargestOutflow = (outflows) => {
+    if (outflows == null || outflows.length === 0) {
+        return undefined;
+    }
+    return outflows.reduce((largest, event) => event.amount.amount > largest.amount.amount ? event : largest);
+};
+export const getCashManagementOverview = (state) => {
+    const { cashManagementOverviewState, depositAccountListState, paymentAccountListState, treasuryDetailState, } = state;
+    const aggregate = reduceAllFetchState([
+        {
+            fetchState: paymentAccountListState.fetchState,
+            error: paymentAccountListState.error,
+        },
+        {
+            fetchState: depositAccountListState.fetchState,
+            error: depositAccountListState.error,
+        },
+        {
+            fetchState: treasuryDetailState.fetchState,
+            error: treasuryDetailState.error,
+        },
+        {
+            fetchState: cashManagementOverviewState.banner.fetchState,
+            error: cashManagementOverviewState.banner.error,
+        },
+        {
+            fetchState: state.autoSweepFlowState.fetchState,
+            error: state.autoSweepFlowState.error,
+        },
+    ]);
+    const treasuryBalance = treasuryDetailState.accountSummary?.totalBalance ?? zeroAmount();
+    const bannerView = getCashManagementOverviewBanner(state);
+    // cashBalance is the primary (agent-managed) deposit account's available
+    // balance — the account the banner resolves as primaryFundingAccount — not
+    // the sum of all cash accounts. Zero until that account resolves.
+    const cashBalance = bannerView.primaryFundingAccount?.accountBalance?.available ?? zeroAmount();
+    const totalCash = addAmounts(treasuryBalance, cashBalance);
+    const bannerData = cashManagementOverviewState.banner.data;
+    const inflowEvents = bannerData?.inflows ?? [];
+    const outflowEvents = bannerData?.outflows ?? [];
+    const totalInFlow = sumEventAmounts(inflowEvents);
+    const totalOutFlow = sumEventAmounts(outflowEvents);
+    const cashflow = subtractAmounts(totalInFlow, totalOutFlow);
+    const projectionData = buildProjectionData(cashBalance, inflowEvents, outflowEvents);
+    return {
+        banner: bannerView,
+        cashBalance,
+        cashflow,
+        inflowEvents,
+        outflowEvents,
+        projectionData,
+        totalCash,
+        totalInFlow,
+        totalOutFlow,
+        treasuryBalance,
+        fetchState: aggregate.fetchState,
+        error: aggregate.error,
+        version: 0,
+    };
+};
+/**
+ * Walks the inflow / outflow events in chronological order, stepping the
+ * running balance from today's `cashBalance`. Emits a point per event so the
+ * chart can render colored markers at each cash event. Events with the same
+ * payment date are kept as separate steps (preserves the marker count even
+ * if Recharts overlays them at the same X position).
+ */
+const buildProjectionData = (cashBalance, inflowEvents, outflowEvents) => {
+    const events = [
+        ...inflowEvents.map((e) => ({
+            amount: e.amount,
+            date: e.paymentDate,
+            isInflow: true,
+        })),
+        ...outflowEvents.map((e) => ({
+            amount: e.amount,
+            date: e.paymentDate,
+            isInflow: false,
+        })),
+    ].sort((a, b) => {
+        const diff = a.date.valueOf() - b.date.valueOf();
+        if (diff !== 0) {
+            return diff;
+        }
+        // Same-day tie-breaker: apply outflows before inflows so the projection
+        // shows the worst-case low first, then the recovery — matches the
+        // "show me the dip" framing on the cash management overview.
+        if (a.isInflow === b.isInflow) {
+            return 0;
+        }
+        return a.isInflow ? 1 : -1;
+    });
+    let balance = cashBalance;
+    const points = [{ balance, date: 'Today' }];
+    events.forEach((event) => {
+        balance = event.isInflow
+            ? addAmounts(balance, event.amount)
+            : subtractAmounts(balance, event.amount);
+        points.push({
+            balance,
+            date: event.date.format('MMM D'),
+            isInflow: event.isInflow ? true : undefined,
+            isOutflow: event.isInflow ? undefined : true,
+        });
+    });
+    return points;
+};
+const sumEventAmounts = (events) => events.reduce((acc, event) => addAmounts(acc, event.amount), zeroAmount());
+/**
+ * Subtracts `b` from `a`, sharing the currency-match guard with `addAmounts`.
+ * Used to compute net cash flow (`inflow - outflow`).
+ */
+const subtractAmounts = (a, b) => {
+    if (isZeroAmount(b)) {
+        return { ...a };
+    }
+    if (isZeroAmount(a)) {
+        return { ...b, amount: -b.amount };
+    }
+    if (a.currencyCode !== b.currencyCode ||
+        a.currencySymbol !== b.currencySymbol) {
+        console.warn(`cashManagementOverview: skipping balance with mismatched currency. Expected ${a.currencyCode} (${a.currencySymbol}), got ${b.currencyCode} (${b.currencySymbol}).`);
+        return a;
+    }
+    return {
+        amount: a.amount - b.amount,
+        currencyCode: a.currencyCode,
+        currencySymbol: a.currencySymbol,
+    };
+};
+const isZeroAmount = (a) => a.amount === 0 && a.currencyCode === 'USD' && a.currencySymbol === '$';
+/**
+ * Adds two Amounts. Currencies must match (the seeded zeroAmount() counts as
+ * "no currency yet" and adopts `b`'s currency). Mismatches return `a`
+ * unchanged and warn — mixing currencies in a total is a bug, not silent
+ * conversion.
+ */
+const addAmounts = (a, b) => {
+    if (isZeroAmount(a)) {
+        return { ...b };
+    }
+    if (a.currencyCode !== b.currencyCode ||
+        a.currencySymbol !== b.currencySymbol) {
+        console.warn(`cashManagementOverview: skipping balance with mismatched currency. Expected ${a.currencyCode} (${a.currencySymbol}), got ${b.currencyCode} (${b.currencySymbol}).`);
+        return a;
+    }
+    return {
+        amount: a.amount + b.amount,
+        currencyCode: a.currencyCode,
+        currencySymbol: a.currencySymbol,
+    };
+};

package/lib/esm/view/spendManagement/cashManagement/cashManagementOverview/cashManagementOverviewState.js

@@ -0,0 +1,10 @@
+export const initialCashManagementBannerState = {
+    fetchState: 'Not-Started',
+    error: undefined,
+    data: undefined,
+};
+export const initialCashManagementRecentTransferState = {
+    fetchState: 'Not-Started',
+    error: undefined,
+    data: undefined,
+};

package/lib/esm/view/spendManagement/cashManagement/cashManagementOverview/epics/fetchCashManagementBannerEpic.js

@@ -0,0 +1,23 @@
+import { from } from 'rxjs';
+import { filter, mergeMap } from 'rxjs/operators';
+import { fetchCashManagementSettings } from '../../autoSweepFlow/autoSweepFlowReducer';
+import { fetchCashManagementBanner, fetchCashManagementRecommendation, fetchRecentTransfer, } from '../cashManagementOverviewReducer';
+export const fetchCashManagementBannerEpic = (actions$, state$) => actions$.pipe(filter(fetchCashManagementBanner.match), mergeMap((action) => {
+    const { cacheOverride } = action.payload;
+    const state = state$.value;
+    const actions = [];
+    if (cacheOverride === true ||
+        needsFetch(state.cashManagementOverviewState.banner.fetchState)) {
+        actions.push(fetchCashManagementRecommendation());
+    }
+    if (cacheOverride === true ||
+        needsFetch(state.autoSweepFlowState.fetchState)) {
+        actions.push(fetchCashManagementSettings());
+    }
+    if (cacheOverride === true ||
+        needsFetch(state.cashManagementOverviewState.recentTransfer.fetchState)) {
+        actions.push(fetchRecentTransfer());
+    }
+    return from(actions);
+}));
+const needsFetch = (fetchState) => fetchState !== 'Completed' && fetchState !== 'In-Progress';