/* ============================================================
CurrencyDesk OS — Cash on Hand · Vault
The treasury pillar, reading the one book.
THIS SCREEN USED TO DERIVE THE SAFE'S CONTENTS IN THE BROWSER, from a
demo opening baseline plus every posted record, and it announced
$594,124.00 across nine currencies for a vault that was empty until
somebody counted it. The Assign modal showed three different balances
for the same safe on one screen — GBP 6,111.05 on the "to a person"
tab, 8,000 on the "to a till" tab, 8,000 behind it on Position, and 0
in the ledger — and a red bar two lines under the 8,000 read "The vault
holds 0.00 GBP". And the P&L tab printed "Unrealized +$4,813.65" over
currencies whose avg_cost is NULL on the server.
Every one of those is the same defect: a second book. So:
• Position — GET /api/ledger/position. Quantity, average cost and
unrealized P&L as the ledger states them, with "—" and
a reason wherever it has no answer. Nothing here
multiplies a quantity by a rate for itself.
• Floats — one source for every balance on the screen. The assign
modal reads the same vault figures the Position tab
does, so one currency cannot show two numbers.
• Orders — a delivery is a recorded movement into the safe.
• P&L — GET /api/ledger/summary. Realized profit from the
figure the disposal wrote, per docs/COST_BASIS.md,
never a spread against a market mid.
The vault owns only accountability records (shifts). Cash is the
ledger's — see docs/CASH_OWNERSHIP_INVARIANTS.md — and an absent
figure is shown as absent, per docs/ABSENT_FIGURES.md.
============================================================ */
(function () {
const { useState, useMemo, useEffect } = React;
const { CD, Ic, fmt, num, crossRate, Absent, businessDate, useDeskFacts, STAFF, deskPack, reportingLimit } = window.CDOS;
/* THE DESK'S OWN CURRENCY. The ledger's `position` and `vault` reads
both carry `homeCurrency`, so most of this screen already had the
right answer to hand; the float modals, the shift settlements and the
order-received log did not, and printed Canadian dollars on every
desk. This is the fallback for the handful of places that have no
server response in scope. */
const homeCcy = () => { const pack = deskPack(); return (pack && pack.homeCurrency) || (reportingLimit(null) || {}).currency || 'CAD'; };
const fmtHome = (v) => v == null ? '—' : fmt(v, homeCcy());
const flagOf = (c) => { try { return (typeof CUR !== 'undefined' ? (CUR.find(x => x.code === c) || {}).flag : '') || ''; } catch (e) { return ''; } };
/* Display-only conversion, for totalling a float across currencies in
the assign modal. It never produces a HOLDING — every quantity on
this screen came from the ledger. */
const cadPer = (c) => c === 'CAD' ? 1 : (crossRate(c, 'CAD') || 0);
const cadVal = (units, c) => (+units || 0) * cadPer(c);
/* ---- the branch's position, from the book ----
One fetch, shared by every tab, re-read whenever cash has moved
(`cashVersion` ticks on each recorded movement). `error` is rendered,
not swallowed: a screen that fails to reach the ledger and shows its
last figures anyway is the second book coming back. */
function useLedgerPosition(serverBacked, cashVersion) {
const [state, setState] = useState({ loading: true, data: null, error: '' });
useEffect(() => {
if (!serverBacked || !window.CDOS.Backend) {
setState({ loading: false, data: null, error: 'This desk is not signed in to the ledger, so it cannot say what the safe holds.' });
return;
}
let live = true;
setState(s => ({ ...s, loading: true }));
window.CDOS.Backend.loadLedgerPosition()
.then(data => { if (live) setState({ loading: false, data, error: '' }); })
.catch(error => { if (live) setState({ loading: false, data: null, error: (error && error.message) || 'The ledger could not be reached.' }); });
return () => { live = false; };
}, [serverBacked, cashVersion]);
return state;
}
/* What the SAFE holds, per currency, as the ledger states it. Returns
null for a currency the vault has no row for — which is not zero, and
the callers below are careful about the difference. */
function vaultRowsOf(position) {
if (!position || !position.vaultTracked) return null;
return (position.currencies || [])
.filter(row => row.vault)
.map(row => ({ c: row.currency, ...row.vault, marketUnitHome: row.marketUnitHome }));
}
const SKEY = 'cdos_vault_shifts';
/* The currencies a shift float is issued in, before the owner has chosen.
The desk's own currency belongs on that list wherever the desk is; the
other three are a starting suggestion the owner edits. */
const DEFAULT_FC = () => Array.from(new Set([homeCcy(), 'USD', 'EUR', 'GBP']));
/* What a wholesale order can be placed in. The ledger carries these four
today (see the scope limits in docs/CASH_OWNERSHIP_INVARIANTS.md), and
offering the other five would let somebody record a delivery the book
cannot take. The nine-currency list this replaced was the demo seed's. */
/* Evaluated per render, not once at module load: the pack arrives from
the server after this file has been parsed, so a constant captured here
would freeze whatever the fallback said. */
const ORDER_CCYS = () => DEFAULT_FC();
const floatCcysOf = (settings) => (settings && Array.isArray(settings.floatCcys) && settings.floatCcys.length) ? settings.floatCcys : DEFAULT_FC();
/* reorder bands — min (reorder point) / target / max in UNITS */
const BANDS = {
CAD: { min: 120000, target: 250000, max: 400000 },
USD: { min: 40000, target: 90000, max: 150000 },
EUR: { min: 18000, target: 35000, max: 60000 },
GBP: { min: 8000, target: 16000, max: 28000 },
INR: { min: 2500000, target: 4500000, max: 7000000 },
PHP: { min: 1200000, target: 2000000, max: 3200000 },
CNY: { min: 120000, target: 240000, max: 400000 },
MXN: { min: 200000, target: 400000, max: 650000 },
AED: { min: 35000, target: 70000, max: 120000 },
};
/* Shifts are accountability records — who had which float on the desk —
and they are this screen's own, kept on the device.
Sixteen invented settled shifts used to be WRITTEN INTO localStorage
here on first render, so "variance by person" opened with three weeks
of track record for people who had never worked a day and drawers
that had never been counted. A real desk starts with none, and the
empty state below says so. */
function loadShifts() {
try { const saved = JSON.parse(localStorage.getItem(SKEY) || 'null'); return Array.isArray(saved) ? saved : []; }
catch (e) { return []; }
}
/* floors: the owner's Settings → Vault floors override the built-in reorder bands.
CAD uses the base-currency reserve floor; others use per-currency floors. */
const floorOf = (c, settings) => {
if (settings) {
if (c === homeCcy() && settings.vaultReserveCad != null && settings.vaultReserveCad !== '' && +settings.vaultReserveCad > 0) return +settings.vaultReserveCad;
const f = settings.vaultFloors && settings.vaultFloors[c];
if (f != null && f !== '' && +f > 0) return +f;
}
return BANDS[c] ? BANDS[c].min : 0;
};
function bandStatus(c, units, settings) {
const b = BANDS[c] || {};
const min = floorOf(c, settings);
if (!min && !b.max) return { tone: CD.mute, label: 'no band', level: 'ok' };
if (min && units < min) return { tone: CD.flag, label: 'below reorder', level: 'low' };
if (b.max && units > b.max) return { tone: CD.amber, label: 'over-stocked', level: 'high' };
return { tone: CD.green, label: 'in band', level: 'ok' };
}
/* ===================== shared bits ===================== */
function Stat({ label, value, sub, tone, big }) {
return (
{parts.map((p, i) => { const w = total ? (p.mkt / total) * 100 : 0; if (w < 0.4) return null;
const shade = `hsl(${(i * 47) % 360} 8% ${22 + (i % 5) * 11}%)`;
return ; })}
);
}
/* ===================== POSITION (the ledger's, not ours) ===================== */
function Position({ position, loading, error, settings, vaultTracked, onRecordOpening }) {
const home = (position && position.homeCurrency) || 'CAD';
const rows = vaultRowsOf(position);
/* Three genuinely different states, and they used to render the same.
A vault nobody has declared is not an empty vault, and an empty
vault is not a vault worth $594,124. */
if (loading) return
Reading the vault off the ledger…
;
if (error) return (
{error} Nothing is shown here rather than a figure from somewhere else.
);
if (!rows) return (
This vault has no opening position on the ledger, so there is nothing it can say the safe holds. Count it once and record it — after that every float, delivery and run is checked against it.
{onRecordOpening && }
);
const totals = (position && position.vaultTotals) || { currencies: 0, marketValueHome: null, costBasisHome: null, unrealizedPnlHome: null };
const held = rows.filter(r => Number(r.quantity) > 0);
/* Concentration and the FX share are shares of a total, so they mean
nothing unless the total does. Where the ledger could not value
every currency it says so instead of dividing by a partial sum. */
const totalMkt = totals.marketValueHome == null ? null : Number(totals.marketValueHome);
const fxMkt = totalMkt == null ? null : held
.filter(r => r.c !== home)
.reduce((sum, r) => sum + Number(r.marketValueHome || 0), 0);
const top = held.slice().sort((a, b) => Number(b.marketValueHome || 0) - Number(a.marketValueHome || 0))[0] || null;
const unvalued = (position.unvaluedCurrencies || []).filter(c => held.some(r => r.c === c));
const unpriced = (position.unpricedCurrencies || []).filter(c => held.some(r => r.c === c));
const lowN = held.filter(r => bandStatus(r.c, Number(r.quantity), settings).level === 'low').length;
const pct = (part) => totalMkt ? Math.round((part / totalMkt) * 100) : null;
return (
: fmt(totals.marketValueHome, home)}
sub={`market value · ${held.length} currenc${held.length === 1 ? 'y' : 'ies'} on the ledger`} />
: pct(fxMkt) + '%'}
sub={fxMkt == null ? 'unknown' : `${fmt(fxMkt, home)} not in ${home}`}
tone={pct(fxMkt) != null && pct(fxMkt) > 70 ? CD.amber : CD.ink} />
: pct(Number(top.marketValueHome)) + '%'}
sub={top ? `${top.c} ${flagOf(top.c)}` : ''} />
{/* The tile that used to be pure fiction: it printed +$4,461.13 over
currencies whose average cost is NULL on the server. There is no
honest figure to put there and now there isn't one. */}
: (Number(totals.unrealizedPnlHome) >= 0 ? '+' : '') + fmt(totals.unrealizedPnlHome, home)}
sub="market vs cost basis"
tone={totals.unrealizedPnlHome == null ? CD.faint : Number(totals.unrealizedPnlHome) >= 0 ? CD.green : CD.flag} />
Every figure here is the ledger's — the safe's recorded balance, the average it actually paid, and the branch's own published board. A dash means the book has no answer, not zero: {unpriced.length ? `${unpriced.join(', ')} reached the safe without a recorded price` : 'nothing is missing a price'}{unvalued.length ? ` · no board rate published for ${unvalued.join(', ')}` : ''}. Reorder floors follow Settings → Vault{lowN ? ` · ${lowN} below floor` : ''}.
);
}
/* ===================== SHIFTS (per-teller float + blind count) ===================== */
function Shifts({ rows, position, me, log, shifts, setShifts, settings, setSettings, branches, station, onIssueTill }) {
const [assigning, setAssigning] = useState(false);
const [settling, setSettling] = useState(null);
const fc = floatCcysOf(settings);
// the branch you're standing in — assignment targets live here
const myB = (branches || []).find(b => b.id === (station && station.branchId)) || (branches || [])[0];
const roster = ((settings && settings.employees && settings.employees.length ? settings.employees : STAFF) || []).filter(e => e.active !== false && e.role !== 'Owner');
const tellers = roster.filter(e => e.branches === '*' || !myB || !Array.isArray(e.branches) || e.branches.includes(myB.id));
const tills = ((myB && myB.tills) || []).filter(t => t.status !== 'closed');
/* ONE SOURCE FOR WHAT THE SAFE HOLDS.
There used to be two functions here — `vaultAvailOf` reading this
branch's local record for the "to a till" tab, and `availOf`
deriving a pooled figure for the "to a person" tab — so the same
modal showed GBP 6,111.05 on one tab and 8,000 on the other, over a
vault the ledger said held nothing. Both tabs now read the ledger's
vault row, and a currency with no row answers null so the modal can
say "the ledger has no figure" instead of "0". */
const vaultRows = vaultRowsOf(position);
const vaultAvailOf = (c) => {
if (!vaultRows) return null;
const row = vaultRows.find(r => r.c === c);
return row ? Number(row.quantity) : null;
};
const ccyChoices = Array.from(new Set([...DEFAULT_FC(), ...fc, ...((vaultRows || []).map(r => r.c))]));
const open = shifts.filter(s => s.status === 'open');
const settled = shifts.filter(s => s.status === 'settled').sort((a, b) => (b.settledAt || '').localeCompare(a.settledAt || ''));
const byPerson = useMemo(() => {
const m = {};
settled.forEach(s => { const k = s.teller; (m[k] = m[k] || { teller: k, shifts: 0, net: 0, abs: 0 }); m[k].shifts++; m[k].net += (+s.varCad || 0); m[k].abs += Math.abs(+s.varCad || 0); });
return Object.values(m).sort((a, b) => a.abs - b.abs);
}, [shifts]);
// expected for a shift = the float handed over + that teller's net ledger
// movement during the shift. Pure read of posted records — no stock mutation.
const expectedFor = (shift, c) => {
const opening = (shift.opening && shift.opening[c]) || 0;
const inSum = rows.filter(r => r.status !== 'void' && r.teller === shift.teller && r.date === shift.date && r.inCcy === c).reduce((s, r) => s + (+r.inAmt || 0), 0);
const outSum = rows.filter(r => r.status !== 'void' && r.teller === shift.teller && r.date === shift.date && r.outCcy === c).reduce((s, r) => s + (+r.outAmt || 0), 0);
return opening + inSum - outSum;
};
// assigning a float is accountability + location only: total holdings are
// INVARIANT across it (the cash was already in the pool). No setVault here.
const doAssign = (teller, opening) => {
const sh = { id: Date.now(), teller, date: businessDate(), openedAt: new Date().toLocaleString('en-CA', { hour12: false }).replace(',', ''), openedBy: me.name, opening: { ...opening }, status: 'open', blind: true };
setShifts(s => [sh, ...s]);
log && log('Shift float assigned', `${teller} · ${fmtHome(fc.reduce((t, c) => t + cadVal(+opening[c] || 0, c), 0))} on the desk (accountability — holdings unchanged)`);
setAssigning(false);
};
// vault → till: real cash, so the modal only closes once the movement has
// actually been taken (by the ledger on a server-backed desk, locally
// otherwise). A refusal comes back to the modal and stays on screen.
const doIssueTill = async (tId, opening) => {
if (!onIssueTill) { setAssigning(false); return { ok: true }; }
const result = await onIssueTill(tId, opening);
if (result && result.ok === false) return result;
setAssigning(false);
return { ok: true };
};
const doSettle = (shift, counted) => {
let varCad = 0;
Object.keys(shift.opening || {}).forEach(c => { varCad += cadVal((+counted[c] || 0) - expectedFor(shift, c), c); });
setShifts(list => list.map(s => s.id === shift.id ? { ...s, status: 'settled', counted: { ...counted }, varCad: Math.round(varCad), settledAt: new Date().toLocaleString('en-CA', { hour12: false }).replace(',', ''), settledBy: me.name } : s));
log && log('Shift settled', `${shift.teller} · ${Math.abs(varCad) < 0.5 ? 'balanced' : (varCad > 0 ? '+' : '') + fmtHome(varCad)} variance`);
setSettling(null);
};
const toggleFc = (c) => {
if (c === homeCcy()) return; // the desk's own currency is always active
const cur = fc.slice();
const next = cur.includes(c) ? cur.filter(x => x !== c) : [...cur, c];
setSettings(s => ({ ...s, floatCcys: next.length ? next : [homeCcy()] }));
};
return (
Assign money — to a person or a till
To a person: a shift float — accountability, settled at close, variance lands on the name. To a till: cash physically moves vault → drawer on the rail, recorded in History.
{/* active float currencies — a setting (Tel Aviv shop sets its own) */}
Active float currencies
{ccyChoices.map(c => { const on = fc.includes(c); const locked = c === homeCcy(); return (
); })}
{open.length > 0 &&
On the floor now
{open.map(s => { const floatCad = Object.keys(s.opening || {}).reduce((t, c) => t + cadVal(s.opening[c] || 0, c), 0); return (
);
}
/* ===================== THE OPENING POSITION =====================
Stated once, by a person who has counted the safe. From then on the
figure only moves through a recorded movement — which is the whole
reason the ledger can refuse a float the vault cannot cover. */
function OpeningPositionModal({ fc, onClose, onSave }) {
const [amounts, setAmounts] = useState(() => Object.fromEntries(fc.map(c => [c, ''])));
const [err, setErr] = useState('');
const [saving, setSaving] = useState(false);
const entered = fc.filter(c => String(amounts[c] ?? '').trim() !== '' && +amounts[c] >= 0);
const totalCad = entered.reduce((t, c) => t + cadVal(+amounts[c] || 0, c), 0);
const submit = async () => {
if (!entered.length || saving) return;
setSaving(true); setErr('');
try {
const result = await onSave(Object.fromEntries(entered.map(c => [c, (+amounts[c] || 0).toFixed(2)])));
if (result && result.ok === false) setErr(result.message || 'That opening position was refused.');
else onClose();
} catch (e) {
setErr((e && e.message) || 'That opening position was refused.');
} finally { setSaving(false); }
};
return (
Leave a currency blank if the safe holds none of it — only what you type is recorded, and a currency you leave out stays absent from the book rather than being set to zero. This can only be set once; after that, corrections are movements, so the trail stays honest.
{/* An opening position states a QUANTITY. What that cash cost is a
separate question, and one this desk may genuinely not be able to
answer — the safe can predate the software. Saying so here is
better than the P&L tab silently reading "—" next week with no
explanation of why. The ledger accepts a unit cost alongside these
balances; wiring the field is tracked work. */}
This records how much is in the safe, not what it cost. Until a priced delivery arrives, the Position tab will show these currencies with no average cost and no unrealized P&L — which is the truth, not a gap.
{err &&
{err}
}
Opening value {fmtHome(totalCad)}
);
}
/* ONE MODAL, ONE SAFE, ONE NUMBER PER CURRENCY.
Both tabs read `vaultAvailOf`, which is the ledger's vault row and
nothing else. It answers null for a currency the vault has no row
for, and null is rendered "—", never 0: the modal used to print
"vault holds 8,000" on the row while a red bar two lines below read
"The vault holds 0.00 GBP — this movement would overdraw it".
The float amounts start EMPTY. They used to be pre-filled with 5,000
CAD and 2,000 USD, which is somebody else's opening float and reads
as a recommendation from the software about a drawer it knows
nothing about. */
function AssignModal({ tellers, tills, branchCode, fc, vaultTracked, vaultAvailOf, onClose, onAssign, onIssueTill }) {
const [target, setTarget] = useState('person'); // 'person' = accountability · 'till' = cash moves on the rail
const [teller, setTeller] = useState(tellers[0] ? tellers[0].name : '');
const [tillId, setTillId] = useState(tills && tills[0] ? tills[0].id : '');
const [opening, setOpening] = useState(() => Object.fromEntries(fc.map(c => [c, ''])));
const floatCad = fc.reduce((t, c) => t + cadVal(+opening[c] || 0, c), 0);
/* Short only where the ledger has a figure to be short against. A
currency it cannot answer for blocks the movement separately below
— refusing is right, but calling it "short" would imply the safe
was counted and came up empty. */
const short = fc.filter(c => { const have = vaultAvailOf(c); return have != null && (+opening[c] || 0) > have; });
const unknown = fc.filter(c => (+opening[c] || 0) > 0 && vaultAvailOf(c) == null);
const tillOk = target !== 'till' || !!tillId;
const valid = tillOk && (target === 'till' || !!teller) && short.length === 0 && unknown.length === 0 && floatCad > 0;
const [issueErr, setIssueErr] = useState('');
const [issuing, setIssuing] = useState(false);
const submit = async () => {
if (!valid || issuing) return;
if (target !== 'till') { onAssign(teller, opening); return; }
setIssuing(true); setIssueErr('');
try {
const result = await onIssueTill(tillId, opening);
if (result && result.ok === false) setIssueErr(result.message || 'That float was refused.');
} catch (e) {
setIssueErr((e && e.message) || 'That float was refused.');
} finally { setIssuing(false); }
};
return (
{/* who gets it — a person (accountability) or a till (cash moves) */}
{[['person', 'To a person', 'Shift float · settled at close'], ['till', 'To a till', 'Vault → drawer · moves cash']].map(([id, label, sub]) => { const on = target === id; return (
); })}
The vault is short on {short.join(', ')} — reduce the amount or replenish first.
}
{unknown.length > 0 &&
{vaultTracked ? `This vault has no ${unknown.join(', ')} on the ledger, so nothing can be issued from it. Record a delivery first.` : 'This vault has no opening position on the ledger yet — count the safe and record it before moving cash out of it.'}
}
{issueErr &&
{issueErr}
}
{target === 'person' ? 'Float value ' : 'Moving '}{fmtHome(floatCad)}
)}
);
}
/* ===================== ORDERS (on order → received) ===================== */
// Creating an order is the header's job (one entry point). Low balances are
// notifications, not cards here. This tab just lists orders: what's on the way,
// and what's landed.
function Orders({ receipts, pending, onOrder, onCancel }) {
const received = (receipts || []).filter(o => o.status === 'received').slice().sort((a, b) => (b.date || '').localeCompare(a.date || ''));
return (
Orders
Place an order with Order up top; mark it received when the cash lands — that's what lifts inventory and re-weights cost basis. Low balances arrive as notifications.
{/* on order — pending, awaiting delivery */}
On order · awaiting delivery
{pending.length > 0 ?
{pending.map(o => (
{flagOf(o.ccy)} {num(o.units)} {o.ccy}
{o.supplier} · placed {o.date}
))}
:
No open orders. Place one with the Order button above.
}
{/* opt-in receive — keeps the consequential action off the default path */}
{!receiveOnly && }
Orders aren’t sent to a wholesaler from the app yet — this records the order. Receiving is what posts the cash to inventory.
);
}
/* ===================== P&L (the figure the disposal wrote) =====================
What a desk earns is the difference between what it paid for a
currency and what it sold it for, and nothing else is profit. That
number is decided once, by dispose(), and stored on the transaction
— so this tab reads it rather than recomputing anything.
What was here before computed a cost basis in the browser from a demo
baseline, compared it against a "mid-spread estimate", and presented
the gap between two guesses as an insight. See docs/COST_BASIS.md. */
function PnL({ summary, loading, error, rangeLabel }) {
if (loading) return
Reading the book…
;
if (error) return (
{error}
);
const home = (summary && summary.homeCurrency) || 'CAD';
const list = ((summary && summary.byCurrency) || []).filter(r => r.deals > 0);
const realized = summary ? summary.realizedPnlHome : null;
const cost = summary ? summary.costOfSaleHome : null;
const fees = summary ? summary.feesHome : null;
const volume = summary ? summary.volumeHome : null;
const posted = summary ? summary.posted : 0;
const priced = summary ? summary.pricedDeals : 0;
/* Margin is a ratio of two ledger figures, and it is only a ratio
when both exist. A zero denominator used to render 0.00%, which
reads as "we made nothing on a busy day" rather than "nothing has
been posted". */
const margin = (realized != null && volume != null && Number(volume) > 0)
? (Number(realized) / Number(volume)) * 100 : null;
const why = posted === 0 ? 'nothing posted in this period' : 'no cost basis on these deals';
return (
Every figure here is the one the sale itself booked — proceeds minus what those notes cost, decided at the moment of the disposal and stored on the transaction. It is not a spread against a market mid, and nothing on this screen recomputes it. {priced < posted && posted > 0 ? `${posted - priced} deal${posted - priced === 1 ? '' : 's'} in this period carr${posted - priced === 1 ? 'ies' : 'y'} no cost basis and ${posted - priced === 1 ? 'is' : 'are'} left out of the profit above.` : ''}
{/* A server-backed desk whose strong room has never been declared. The
ledger will not police what nobody has stated, so it says so plainly
rather than quietly balancing against zero. */}
{serverBacked && !posLoading && !onLedger && (
This vault isn’t on the ledger yet
Count the safe once and record it. After that every float, delivery and run is checked against it, and a drawer can’t be floated with money the vault doesn’t have.
Nothing on the rail yet — issue a float, receive an order, or run cash between vaults.
}
Every dollar in and out of this vault, recorded forever — floats to tills, returns at close, wholesale orders received, and runs to other branches. The full network view lives in .