@zeniai/client-epic-state 5.0.81 → 5.0.82-betaAK1

package/lib/view/spendManagement/cashManagement/autoSweepFlow/autoSweepFlowState.d.ts

@@ -0,0 +1,44 @@
+import { Amount } from '../../../../commonStateTypes/amount';
+import { FetchStateAndError, ID } from '../../../../commonStateTypes/common';
+/**
+ * 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 declare const ALL_AUTO_SWEEP_FREQUENCIES: readonly ["daily", "weekly", "biweekly", "monthly"];
+export declare const toAutoSweepFrequency: (v?: string) => "weekly" | "biweekly" | "monthly" | "daily";
+export type AutoSweepFrequency = NonNullable<ReturnType<typeof toAutoSweepFrequency>>;
+/**
+ * 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 declare const ALL_AUTO_SWEEP_RISK_LEVELS: readonly ["low", "moderate", "high"];
+export declare const toAutoSweepRiskLevel: (v?: string) => "high" | "low" | "moderate";
+export type RiskLevel = NonNullable<ReturnType<typeof toAutoSweepRiskLevel>>;
+export declare const RISK_BUFFER_AMOUNT: Record<RiskLevel, number>;
+/**
+ * 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 declare const bufferAmountToRisk: (amount: number) => RiskLevel;
+/**
+ * Auto-sweep configuration state.
+ *
+ * `fetchState` / `error` (inherited from `FetchStateAndError`) track the
+ * GET `/cash-management/settings` fetch. `saveStatus` tracks the PUT save
+ * separately so the two flows don't stomp on each other's status.
+ *
+ * `settingsId` is the server-issued id (nullable on the wire — undefined
+ * here when the agent has no settings record yet).
+ */
+export interface AutoSweepFlowState extends FetchStateAndError {
+    bufferAmount: Amount;
+    frequency: AutoSweepFrequency;
+    memo: string;
+    saveStatus: FetchStateAndError;
+    settingsId?: ID;
+}
+export declare const initialAutoSweepFlowState: AutoSweepFlowState;

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

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.initialAutoSweepFlowState = exports.bufferAmountToRisk = exports.RISK_BUFFER_AMOUNT = exports.toAutoSweepRiskLevel = exports.ALL_AUTO_SWEEP_RISK_LEVELS = exports.toAutoSweepFrequency = exports.ALL_AUTO_SWEEP_FREQUENCIES = void 0;
+const amount_1 = require("../../../../commonStateTypes/amount");
+const stringToUnion_1 = require("../../../../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).
+ */
+exports.ALL_AUTO_SWEEP_FREQUENCIES = [
+    'daily',
+    'weekly',
+    'biweekly',
+    'monthly',
+];
+const toAutoSweepFrequency = (v) => (0, stringToUnion_1.stringToUnion)(v ?? '', exports.ALL_AUTO_SWEEP_FREQUENCIES);
+exports.toAutoSweepFrequency = toAutoSweepFrequency;
+/**
+ * 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.
+ */
+exports.ALL_AUTO_SWEEP_RISK_LEVELS = ['low', 'moderate', 'high'];
+const toAutoSweepRiskLevel = (v) => (0, stringToUnion_1.stringToUnion)(v ?? '', exports.ALL_AUTO_SWEEP_RISK_LEVELS);
+exports.toAutoSweepRiskLevel = toAutoSweepRiskLevel;
+exports.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.
+ */
+const bufferAmountToRisk = (amount) => {
+    const match = Object.entries(exports.RISK_BUFFER_AMOUNT).find(([, presetAmount]) => presetAmount === amount);
+    return match != null ? match[0] : 'moderate';
+};
+exports.bufferAmountToRisk = bufferAmountToRisk;
+exports.initialAutoSweepFlowState = {
+    bufferAmount: (0, amount_1.toAmount)(10000, 'USD'),
+    frequency: 'weekly',
+    memo: '',
+    saveStatus: { fetchState: 'Not-Started', error: undefined },
+    settingsId: undefined,
+    fetchState: 'Not-Started',
+    error: undefined,
+};

package/lib/view/spendManagement/cashManagement/autoSweepFlow/epics/fetchCashManagementSettingsEpic.d.ts

@@ -0,0 +1,16 @@
+import { ActionsObservable, StateObservable } from 'redux-observable';
+import { Observable } from 'rxjs';
+import { RootState } from '../../../../../reducer';
+import { ZeniAPI } from '../../../../../zeniAPI';
+import { fetchCashManagementSettings, updateCashManagementSettings, updateCashManagementSettingsFetchStatus } from '../autoSweepFlowReducer';
+export type ActionType = ReturnType<typeof fetchCashManagementSettings> | ReturnType<typeof updateCashManagementSettings> | ReturnType<typeof updateCashManagementSettingsFetchStatus>;
+/**
+ * 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.
+ *
+ * TODO: switch the endpoint to a base URL constant once the prod endpoint
+ * lands; right now this hits the dev environment directly.
+ */
+export declare const fetchCashManagementSettingsEpic: (actions$: ActionsObservable<ActionType>, _state$: StateObservable<RootState>, zeniAPI: ZeniAPI) => Observable<ActionType>;

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

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fetchCashManagementSettingsEpic = void 0;
+const rxjs_1 = require("rxjs");
+const operators_1 = require("rxjs/operators");
+const responsePayload_1 = require("../../../../../responsePayload");
+const autoSweepFlowReducer_1 = require("../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.
+ *
+ * TODO: switch the endpoint to a base URL constant once the prod endpoint
+ * lands; right now this hits the dev environment directly.
+ */
+const fetchCashManagementSettingsEpic = (actions$, _state$, zeniAPI) => actions$.pipe((0, operators_1.filter)(autoSweepFlowReducer_1.fetchCashManagementSettings.match), (0, operators_1.switchMap)(() => zeniAPI
+    .getJSON(`https://dev.api.zeni.ai/cash-management-agent/1.0/cash-management/settings`)
+    .pipe((0, operators_1.mergeMap)((response) => {
+    if ((0, responsePayload_1.isSuccessResponse)(response) && response.data != null) {
+        return (0, rxjs_1.of)((0, autoSweepFlowReducer_1.updateCashManagementSettings)({ data: response.data }));
+    }
+    return (0, rxjs_1.of)((0, autoSweepFlowReducer_1.updateCashManagementSettingsFetchStatus)({
+        fetchState: 'Error',
+        error: response.status,
+    }));
+}), (0, operators_1.catchError)((error) => (0, rxjs_1.of)((0, autoSweepFlowReducer_1.updateCashManagementSettingsFetchStatus)({
+    fetchState: 'Error',
+    error: (0, responsePayload_1.createZeniAPIStatus)('Unexpected Error', 'Fetch cash management settings REST API call errored out' +
+        JSON.stringify(error)),
+}))))));
+exports.fetchCashManagementSettingsEpic = fetchCashManagementSettingsEpic;

package/lib/view/spendManagement/cashManagement/autoSweepFlow/epics/saveAutoSweepSettingsEpic.d.ts

@@ -0,0 +1,14 @@
+import { ActionsObservable, StateObservable } from 'redux-observable';
+import { Observable } from 'rxjs';
+import { RootState } from '../../../../../reducer';
+import { ZeniAPI } from '../../../../../zeniAPI';
+import { saveAutoSweepSettings, updateAutoSweepSettingsFetchStatus } from '../autoSweepFlowReducer';
+export type ActionType = ReturnType<typeof saveAutoSweepSettings> | ReturnType<typeof updateAutoSweepSettingsFetchStatus>;
+/**
+ * Hits `PUT /cash-management/settings` with the values the user just
+ * confirmed in the auto-sweep flow.
+ *
+ * TODO: switch the endpoint to a base URL constant once the prod endpoint
+ * lands; right now this hits the dev environment directly.
+ */
+export declare const saveAutoSweepSettingsEpic: (actions$: ActionsObservable<ActionType>, _state$: StateObservable<RootState>, zeniAPI: ZeniAPI) => Observable<ActionType>;

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

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.saveAutoSweepSettingsEpic = void 0;
+const rxjs_1 = require("rxjs");
+const operators_1 = require("rxjs/operators");
+const responsePayload_1 = require("../../../../../responsePayload");
+const autoSweepFlowPayload_1 = require("../autoSweepFlowPayload");
+const autoSweepFlowReducer_1 = require("../autoSweepFlowReducer");
+/**
+ * Hits `PUT /cash-management/settings` with the values the user just
+ * confirmed in the auto-sweep flow.
+ *
+ * TODO: switch the endpoint to a base URL constant once the prod endpoint
+ * lands; right now this hits the dev environment directly.
+ */
+const saveAutoSweepSettingsEpic = (actions$, _state$, zeniAPI) => actions$.pipe((0, operators_1.filter)(autoSweepFlowReducer_1.saveAutoSweepSettings.match), (0, operators_1.switchMap)((action) => zeniAPI
+    .putAndGetJSON(`https://dev.api.zeni.ai/cash-management-agent/1.0/cash-management/settings`, (0, autoSweepFlowPayload_1.toSaveAutoSweepSettingsBody)(action.payload))
+    .pipe((0, operators_1.mergeMap)((response) => {
+    if ((0, responsePayload_1.isSuccessResponse)(response)) {
+        return (0, rxjs_1.of)((0, autoSweepFlowReducer_1.updateAutoSweepSettingsFetchStatus)({ fetchState: 'Completed' }));
+    }
+    return (0, rxjs_1.of)((0, autoSweepFlowReducer_1.updateAutoSweepSettingsFetchStatus)({
+        fetchState: 'Error',
+        error: response.status,
+    }));
+}), (0, operators_1.catchError)((error) => (0, rxjs_1.of)((0, autoSweepFlowReducer_1.updateAutoSweepSettingsFetchStatus)({
+    fetchState: 'Error',
+    error: (0, responsePayload_1.createZeniAPIStatus)('Unexpected Error', 'Save auto-sweep settings REST API call errored out' +
+        JSON.stringify(error)),
+}))))));
+exports.saveAutoSweepSettingsEpic = saveAutoSweepSettingsEpic;

package/lib/view/spendManagement/cashManagement/cashManagementOverview/cashManagementOverviewPayload.d.ts

@@ -0,0 +1,32 @@
+import { ZeniAPIResponse } from '../../../../responsePayload';
+import { CashManagementBannerData, CashManagementBankAccountType, CashManagementSubMovementType, UpcomingPaymentEvent, UpcomingPaymentEventAccountType } from './cashManagementOverviewState';
+export interface CashAgentEventPayload {
+    account_id: string;
+    account_type: UpcomingPaymentEventAccountType;
+    amount_usd: number;
+    currency_code: string;
+    label: string;
+    payment_date: string;
+}
+export interface CashAgentMovementPayload {
+    amount: number;
+    currency_code: string;
+    destination_bank_account_id: string | null;
+    destination_bank_account_type: CashManagementBankAccountType;
+    reasoning: string;
+    source_bank_account_id: string | null;
+    source_bank_account_type: CashManagementBankAccountType;
+    sub_movement_type: CashManagementSubMovementType;
+}
+export interface CashAgentMoneyMovementGroupPayload {
+    movement_type: string;
+    movements: CashAgentMovementPayload[];
+}
+export interface CashAgentRecommendPayload {
+    inflows: CashAgentEventPayload[];
+    money_movements: CashAgentMoneyMovementGroupPayload[];
+    outflows: CashAgentEventPayload[];
+}
+export type CashAgentRecommendResponse = ZeniAPIResponse<CashAgentRecommendPayload>;
+export declare const toUpcomingPaymentEvent: (event: CashAgentEventPayload) => UpcomingPaymentEvent;
+export declare const toCashManagementBannerData: (payload: CashAgentRecommendPayload) => CashManagementBannerData;

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

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toCashManagementBannerData = exports.toUpcomingPaymentEvent = void 0;
+const amount_1 = require("../../../../commonStateTypes/amount");
+const zeniDayJS_1 = require("../../../../zeniDayJS");
+// ---------------------------------------------------------------------------
+// Converters
+// ---------------------------------------------------------------------------
+const toUpcomingPaymentEvent = (event) => ({
+    accountId: event.account_id,
+    accountType: event.account_type,
+    amount: (0, amount_1.toAmount)(event.amount_usd, event.currency_code),
+    label: event.label,
+    paymentDate: (0, zeniDayJS_1.date)(event.payment_date),
+});
+exports.toUpcomingPaymentEvent = toUpcomingPaymentEvent;
+/**
+ * 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: (0, amount_1.toAmount)(payload.amount, payload.currency_code),
+    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,
+});
+const toCashManagementBannerData = (payload) => ({
+    inflows: payload.inflows.map(exports.toUpcomingPaymentEvent),
+    moneyMovements: payload.money_movements.map(toCashManagementMoneyMovementGroup),
+    outflows: payload.outflows.map(exports.toUpcomingPaymentEvent),
+});
+exports.toCashManagementBannerData = toCashManagementBannerData;

package/lib/view/spendManagement/cashManagement/cashManagementOverview/cashManagementOverviewReducer.d.ts

@@ -0,0 +1,15 @@
+import { FetchState } from '../../../../commonStateTypes/common';
+import { ZeniAPIStatus } from '../../../../responsePayload';
+import { CashAgentRecommendPayload } from './cashManagementOverviewPayload';
+import { CashManagementOverviewState } from './cashManagementOverviewState';
+export declare const initialState: CashManagementOverviewState;
+export declare const fetchCashManagementOverviewPage: import("@reduxjs/toolkit").ActionCreatorWithPreparedPayload<[cacheOverride: boolean], {
+    cacheOverride: boolean;
+}, "cashManagementOverview/fetchCashManagementOverviewPage", never, never>, fetchCashManagementBanner: import("@reduxjs/toolkit").ActionCreatorWithoutPayload<"cashManagementOverview/fetchCashManagementBanner">, updateCashManagementBanner: import("@reduxjs/toolkit").ActionCreatorWithPayload<{
+    data: CashAgentRecommendPayload;
+}, "cashManagementOverview/updateCashManagementBanner">, updateCashManagementBannerFetchStatus: import("@reduxjs/toolkit").ActionCreatorWithPayload<{
+    fetchState: FetchState;
+    error?: ZeniAPIStatus;
+}, "cashManagementOverview/updateCashManagementBannerFetchStatus">, clearCashManagementOverview: import("@reduxjs/toolkit").ActionCreatorWithoutPayload<"cashManagementOverview/clearCashManagementOverview">;
+declare const _default: import("redux").Reducer<CashManagementOverviewState>;
+export default _default;

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

@@ -0,0 +1,53 @@
+"use strict";
+var _a;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.clearCashManagementOverview = exports.updateCashManagementBannerFetchStatus = exports.updateCashManagementBanner = exports.fetchCashManagementBanner = exports.fetchCashManagementOverviewPage = exports.initialState = void 0;
+const toolkit_1 = require("@reduxjs/toolkit");
+const cashManagementOverviewPayload_1 = require("./cashManagementOverviewPayload");
+const cashManagementOverviewState_1 = require("./cashManagementOverviewState");
+exports.initialState = {
+    banner: cashManagementOverviewState_1.initialCashManagementBannerState,
+    fetchState: 'Not-Started',
+    error: undefined,
+    hasValidState() {
+        return this.fetchState == 'Completed';
+    },
+};
+const cashManagementOverview = (0, toolkit_1.createSlice)({
+    name: 'cashManagementOverview',
+    initialState: exports.initialState,
+    reducers: {
+        fetchCashManagementOverviewPage: {
+            reducer() { },
+            prepare(cacheOverride) {
+                return { payload: { cacheOverride } };
+            },
+        },
+        fetchCashManagementBanner(draft) {
+            draft.banner = {
+                ...cashManagementOverviewState_1.initialCashManagementBannerState,
+                fetchState: 'In-Progress',
+                error: undefined,
+            };
+        },
+        updateCashManagementBanner(draft, action) {
+            draft.banner = {
+                fetchState: 'Completed',
+                error: undefined,
+                data: (0, cashManagementOverviewPayload_1.toCashManagementBannerData)(action.payload.data),
+            };
+        },
+        updateCashManagementBannerFetchStatus(draft, action) {
+            draft.banner = {
+                ...draft.banner,
+                fetchState: action.payload.fetchState,
+                error: action.payload.error,
+            };
+        },
+        clearCashManagementOverview(draft) {
+            Object.assign(draft, exports.initialState);
+        },
+    },
+});
+_a = cashManagementOverview.actions, exports.fetchCashManagementOverviewPage = _a.fetchCashManagementOverviewPage, exports.fetchCashManagementBanner = _a.fetchCashManagementBanner, exports.updateCashManagementBanner = _a.updateCashManagementBanner, exports.updateCashManagementBannerFetchStatus = _a.updateCashManagementBannerFetchStatus, exports.clearCashManagementOverview = _a.clearCashManagementOverview;
+exports.default = cashManagementOverview.reducer;

package/lib/view/spendManagement/cashManagement/cashManagementOverview/cashManagementOverviewSelector.d.ts

@@ -0,0 +1,41 @@
+import { Amount } from '../../../../commonStateTypes/amount';
+import { ID } from '../../../../commonStateTypes/common';
+import { SelectorView } from '../../../../commonStateTypes/viewAndReport/viewAndReport';
+import { RootState } from '../../../../reducer';
+import { CashManagementMovement, UpcomingPaymentEvent } from './cashManagementOverviewState';
+export interface CashManagementOverviewBannerSelectorView extends SelectorView, CashManagementMovement {
+    cashManagementSettingsId?: ID;
+}
+/**
+ * One point on the cash-balance projection line. The first point is today's
+ * `cashBalance`; each subsequent point is the running balance after applying
+ * the next inflow / outflow event (in chronological order). The `isInflow` /
+ * `isOutflow` flags drive the colored dot markers in the chart.
+ */
+export interface CashProjectionPoint {
+    balance: number;
+    /** Pre-formatted display label (e.g. `"Today"`, `"May 27"`). */
+    date: string;
+    isInflow?: boolean;
+    isOutflow?: boolean;
+}
+export interface CashManagementOverviewSelectorView extends SelectorView {
+    banner: CashManagementOverviewBannerSelectorView;
+    cashBalance: Amount;
+    /** Net cash flow over the horizon — `totalInFlow` minus `totalOutFlow`.
+     *  Positive = surplus, negative = burn. */
+    cashflow: Amount;
+    inflowEvents: UpcomingPaymentEvent[];
+    outflowEvents: UpcomingPaymentEvent[];
+    /** Running cash-balance projection seeded by `cashBalance` and stepped by
+     *  the inflow / outflow events. */
+    projectionData: CashProjectionPoint[];
+    totalCash: Amount;
+    /** Sum of all `inflowEvents[].amount` values. */
+    totalInFlow: Amount;
+    /** Sum of all `outflowEvents[].amount` values. */
+    totalOutFlow: Amount;
+    treasuryBalance: Amount;
+}
+export declare const getCashManagementOverviewBanner: (state: RootState) => CashManagementOverviewBannerSelectorView;
+export declare const getCashManagementOverview: (state: RootState) => CashManagementOverviewSelectorView;

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

@@ -0,0 +1,184 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getCashManagementOverview = exports.getCashManagementOverviewBanner = void 0;
+const amount_1 = require("../../../../commonStateTypes/amount");
+const reduceFetchState_1 = require("../../../../commonStateTypes/reduceFetchState");
+/**
+ * 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';
+const getCashManagementOverviewBanner = (state) => {
+    const { banner } = 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 = (0, reduceFetchState_1.reduceAllFetchState)([
+        { fetchState: banner.fetchState, error: banner.error },
+        { fetchState: autoSweep.fetchState, error: autoSweep.error },
+    ]);
+    return {
+        fetchState: aggregate.fetchState,
+        error: aggregate.error,
+        amount: movement?.amount ?? (0, amount_1.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: movement?.subMovementType ?? DEFAULT_SUB_MOVEMENT_TYPE,
+        version: 0,
+    };
+};
+exports.getCashManagementOverviewBanner = getCashManagementOverviewBanner;
+const getCashManagementOverview = (state) => {
+    const { cashManagementOverviewState, depositAccountListState, depositAccountState, paymentAccountListState, paymentAccountState, treasuryDetailState, } = state;
+    const aggregate = (0, reduceFetchState_1.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 ?? (0, amount_1.zeroAmount)();
+    const cashBalance = sumCashBalances(paymentAccountListState.paymentAccountIds, paymentAccountState, depositAccountListState.accountIds, depositAccountState);
+    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: (0, exports.getCashManagementOverviewBanner)(state),
+        cashBalance,
+        cashflow,
+        inflowEvents,
+        outflowEvents,
+        projectionData,
+        totalCash,
+        totalInFlow,
+        totalOutFlow,
+        treasuryBalance,
+        fetchState: aggregate.fetchState,
+        error: aggregate.error,
+        version: 0,
+    };
+};
+exports.getCashManagementOverview = getCashManagementOverview;
+/**
+ * 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) => ({
+            date: e.paymentDate,
+            delta: e.amount.amount,
+            isInflow: true,
+        })),
+        ...outflowEvents.map((e) => ({
+            date: e.paymentDate,
+            delta: -e.amount.amount,
+            isOutflow: true,
+        })),
+    ].sort((a, b) => a.date.valueOf() - b.date.valueOf());
+    let balance = cashBalance.amount;
+    const points = [{ balance, date: 'Today' }];
+    events.forEach((event) => {
+        balance += event.delta;
+        points.push({
+            balance,
+            date: event.date.format('MMM D'),
+            isInflow: event.isInflow,
+            isOutflow: event.isOutflow,
+        });
+    });
+    return points;
+};
+const sumEventAmounts = (events) => events.reduce((acc, event) => addAmounts(acc, event.amount), (0, amount_1.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,
+    };
+};
+const sumCashBalances = (paymentAccountIds, paymentAccountState, depositAccountIds, depositAccountState) => {
+    let total = (0, amount_1.zeroAmount)();
+    paymentAccountIds.forEach((id) => {
+        const balance = paymentAccountState.paymentAccountByID[id]?.balances
+            ?.available;
+        if (balance != null) {
+            total = addAmounts(total, balance);
+        }
+    });
+    depositAccountIds.forEach((id) => {
+        const balance = depositAccountState.depositAccountByID[id]?.accountBalance?.available;
+        if (balance != null) {
+            total = addAmounts(total, balance);
+        }
+    });
+    return total;
+};

package/lib/view/spendManagement/cashManagement/cashManagementOverview/cashManagementOverviewState.d.ts

@@ -0,0 +1,71 @@
+import { Amount } from '../../../../commonStateTypes/amount';
+import { FetchStateAndError, FetchedState, ID } from '../../../../commonStateTypes/common';
+import { ZeniDate } from '../../../../zeniDayJS';
+/**
+ * Bank account types the cash agent reports against. Kept as a string union so
+ * the consumer can branch on it; new values from the agent will widen the type
+ * via TypeScript inference and won't break callers handling the known set.
+ */
+export type CashManagementBankAccountType = 'deposit_account' | 'treasury_account';
+/** Direction of a single sweep movement. */
+export type CashManagementSubMovementType = 'push' | 'pull';
+/**
+ * Bank account types reported on upcoming-payment events. Wider than
+ * `CashManagementBankAccountType` because the cash agent can attribute
+ * inflows / outflows to payment accounts too.
+ */
+export type UpcomingPaymentEventAccountType = 'deposit_account' | 'treasury_account' | 'payment_account';
+/**
+ * One projected inflow / outflow returned by the cash agent. Stored on the
+ * banner state directly (no separate entity bucket) because these events are
+ * only meaningful in the context of a banner fetch — they're not addressable
+ * by id from anywhere else.
+ */
+export interface UpcomingPaymentEvent {
+    accountId: ID;
+    accountType: UpcomingPaymentEventAccountType;
+    amount: Amount;
+    label: string;
+    paymentDate: ZeniDate;
+}
+/**
+ * A single recommended money movement returned by the cash agent (e.g.
+ * "sweep $99,100 from checking to treasury"). Mirrors one element of the
+ * `money_movements[].movements` array in the recommend response, with field
+ * names camelCased and `amount`/`currency_code` collapsed into an `Amount`.
+ */
+export interface CashManagementMovement {
+    amount: Amount;
+    destinationBankAccountId: ID;
+    destinationBankAccountType: CashManagementBankAccountType;
+    reasoning: string;
+    sourceBankAccountId: ID;
+    sourceBankAccountType: CashManagementBankAccountType;
+    subMovementType: CashManagementSubMovementType;
+}
+/**
+ * A group of related recommended movements (e.g. all `treasury` sweeps).
+ * `movementType` is left as `string` because the agent may grow new groups
+ * over time; today the only known value is `'treasury'`.
+ */
+export interface CashManagementMoneyMovementGroup {
+    movements: CashManagementMovement[];
+    movementType: string;
+}
+/**
+ * Banner-side data derived from the cash agent's recommend endpoint.
+ * `inflows` and `outflows` carry the full event objects; the selector reads
+ * them directly without an entity-bucket lookup.
+ */
+export interface CashManagementBannerData {
+    inflows: UpcomingPaymentEvent[];
+    moneyMovements: CashManagementMoneyMovementGroup[];
+    outflows: UpcomingPaymentEvent[];
+}
+export interface CashManagementBannerState extends FetchStateAndError {
+    data?: CashManagementBannerData;
+}
+export interface CashManagementOverviewState extends FetchedState {
+    banner: CashManagementBannerState;
+}
+export declare const initialCashManagementBannerState: CashManagementBannerState;

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

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.initialCashManagementBannerState = void 0;
+exports.initialCashManagementBannerState = {
+    fetchState: 'Not-Started',
+    error: undefined,
+    data: undefined,
+};