@@ -37,7 +38,7 @@ export default function QuoteCard({ quote, locale = DEFAULT_LOCALE }) {
Recipient gets
- {formatAmount(receiveAmount, to, locale)}
+ {formatMoney(receiveAmount, to, locale)}
diff --git a/src/components/StatusBadge.css b/src/components/StatusBadge.css
index 43baa1c..f3ef73d 100644
--- a/src/components/StatusBadge.css
+++ b/src/components/StatusBadge.css
@@ -8,6 +8,23 @@
letter-spacing: 0.03em;
}
+/* Pre-submission states share a neutral/blue family; in-flight states are
+ amber; terminal states are green (settled), red (failed) or grey (expired). */
+.status-quoted {
+ background: rgba(99, 102, 241, 0.15);
+ color: #a5b4fc;
+}
+
+.status-validating {
+ background: rgba(56, 189, 248, 0.15);
+ color: #7dd3fc;
+}
+
+.status-authorizing {
+ background: rgba(168, 85, 247, 0.15);
+ color: #d8b4fe;
+}
+
.status-pending {
background: rgba(234, 179, 8, 0.15);
color: #fde047;
@@ -23,7 +40,35 @@
color: #f87171;
}
+.status-expired {
+ background: rgba(148, 163, 184, 0.15);
+ color: #cbd5e1;
+}
+
+/* A status the contract does not recognise. Rendered deliberately plainly so
+ it reads as "unexpected" rather than as one of the known states. */
+.status-unknown {
+ background: rgba(148, 163, 184, 0.12);
+ color: #94a3b8;
+ border: 1px dashed #64748b;
+}
+
@media (prefers-contrast: more) {
+ .status-quoted {
+ background: rgba(99, 102, 241, 0.35);
+ border: 1px solid #a5b4fc;
+ }
+
+ .status-validating {
+ background: rgba(56, 189, 248, 0.35);
+ border: 1px solid #7dd3fc;
+ }
+
+ .status-authorizing {
+ background: rgba(168, 85, 247, 0.35);
+ border: 1px solid #d8b4fe;
+ }
+
.status-pending {
background: rgba(234, 179, 8, 0.35);
border: 1px solid #fde047;
@@ -38,4 +83,9 @@
background: rgba(239, 68, 68, 0.35);
border: 1px solid #f87171;
}
+
+ .status-expired {
+ background: rgba(148, 163, 184, 0.35);
+ border: 1px solid #cbd5e1;
+ }
}
diff --git a/src/components/StatusBadge.jsx b/src/components/StatusBadge.jsx
index f745945..3e75a39 100644
--- a/src/components/StatusBadge.jsx
+++ b/src/components/StatusBadge.jsx
@@ -1,18 +1,56 @@
+import { normalizeStatus } from '../services/contracts/transfer.js';
import './StatusBadge.css';
-// Human-readable labels for each transfer status.
-const LABELS = {
+/**
+ * Human-readable labels for every state in the transfer lifecycle. Exported so
+ * the transfers filter and the badge cannot drift apart; the contract test
+ * asserts this covers TRANSFER_STATUSES exactly.
+ */
+export const TRANSFER_STATUS_LABELS = {
+ quoted: 'Quoted',
+ validating: 'Validating',
+ authorizing: 'Authorizing',
pending: 'Pending',
completed: 'Completed',
failed: 'Failed',
+ expired: 'Expired',
+};
+
+// Short explanations surfaced as a tooltip/accessible description, so a
+// colour-coded pill is not the only way to know what a state means.
+const DESCRIPTIONS = {
+ quoted: 'Quote prepared, not yet submitted',
+ validating: 'Checking recipient and amount',
+ authorizing: 'Waiting for wallet authorization',
+ pending: 'Sent, waiting to settle',
+ completed: 'Funds delivered',
+ failed: 'Transfer did not go through',
+ expired: 'Quote expired before authorization',
};
/**
* Colored badge showing a transfer status.
+ *
+ * Legacy and provider spellings (`settled`, `submitted`, ...) are normalised
+ * through the transfer contract. A genuinely unknown status renders as a
+ * neutral badge with the raw value rather than an unstyled, unlabelled pill.
+ *
* @param {object} props
- * @param {'pending'|'completed'|'failed'} props.status
+ * @param {string} props.status - a status from TRANSFER_STATUSES or a known alias
*/
export default function StatusBadge({ status }) {
- const label = LABELS[status] || status;
- return {label} ;
+ const canonical = normalizeStatus(status);
+ const label = canonical
+ ? TRANSFER_STATUS_LABELS[canonical]
+ : status || 'Unknown';
+ const description = canonical ? DESCRIPTIONS[canonical] : undefined;
+
+ return (
+
+ {label}
+
+ );
}
diff --git a/src/components/StatusBadge.stories.jsx b/src/components/StatusBadge.stories.jsx
index e579ff8..465212c 100644
--- a/src/components/StatusBadge.stories.jsx
+++ b/src/components/StatusBadge.stories.jsx
@@ -1,4 +1,8 @@
import StatusBadge from './StatusBadge.jsx';
+import {
+ TRANSFER_STATUSES,
+ TRANSFER_STATUS_ALIASES,
+} from '../services/contracts/transfer.js';
export default {
title: 'Components/StatusBadge',
@@ -7,35 +11,54 @@ export default {
argTypes: {
status: {
control: 'select',
- options: ['pending', 'completed', 'failed'],
+ // Driven by the contract so the control cannot drift from the data.
+ options: [...TRANSFER_STATUSES, ...Object.keys(TRANSFER_STATUS_ALIASES)],
},
},
};
-export const Pending = {
- args: {
- status: 'pending',
- },
-};
-
-export const Completed = {
- args: {
- status: 'completed',
- },
-};
+export const Quoted = { args: { status: 'quoted' } };
+export const Validating = { args: { status: 'validating' } };
+export const Authorizing = { args: { status: 'authorizing' } };
+export const Pending = { args: { status: 'pending' } };
+export const Completed = { args: { status: 'completed' } };
+export const Failed = { args: { status: 'failed' } };
+export const Expired = { args: { status: 'expired' } };
-export const Failed = {
- args: {
- status: 'failed',
- },
+export const AllStatuses = {
+ render: () => (
+
+ {TRANSFER_STATUSES.map((status) => (
+
+ ),
};
-export const AllStatuses = {
+/** Provider spellings the adapter normalises on the way in. */
+export const LegacySpellings = {
render: () => (
-
-
-
-
+
+ {Object.keys(TRANSFER_STATUS_ALIASES).map((alias) => (
+
),
};
+
+/** A status the contract does not know: visibly unexpected, never blank. */
+export const UnknownStatus = { args: { status: 'in_flight' } };
diff --git a/src/components/TransferRow.jsx b/src/components/TransferRow.jsx
index a677173..7cf0597 100644
--- a/src/components/TransferRow.jsx
+++ b/src/components/TransferRow.jsx
@@ -1,12 +1,15 @@
import StatusBadge from './StatusBadge.jsx';
-import { formatAmount, formatDate, shortenAddress } from '../utils/format.js';
+import { formatDate, shortenAddress } from '../utils/format.js';
+import { formatMoney } from '../utils/money.js';
import { DEFAULT_LOCALE } from '../constants/locales.js';
import './TransferRow.css';
/**
* A single row in the transfers list.
* @param {object} props
- * @param {object} props.transfer - the transfer record
+ * @param {object} props.transfer - a contract-normalised transfer record;
+ * amounts are decimal strings and are rendered with formatMoney so an
+ * unparseable value shows a placeholder rather than a fabricated 0.00
* @param {string} [props.locale] - locale used for currency/date formatting
* @param {boolean} [props.selected] - whether this row is selected
* @param {Function} [props.onToggleSelect] - called when the checkbox is toggled
@@ -43,12 +46,12 @@ export default function TransferRow({
Sent
- {formatAmount(sendAmount, from, locale)}
+ {formatMoney(sendAmount, from, locale)}
Received
- {formatAmount(receiveAmount, to, locale)}
+ {formatMoney(receiveAmount, to, locale)}
diff --git a/src/hooks/useTransfers.js b/src/hooks/useTransfers.js
index fa9d448..45c92cb 100644
--- a/src/hooks/useTransfers.js
+++ b/src/hooks/useTransfers.js
@@ -1,5 +1,6 @@
import { useCallback, useEffect, useState } from 'react';
import { listTransfers, createTransfer } from '../services/api.js';
+import { ContractViolationError } from '../services/contracts/schema.js';
/**
* Hook for loading and creating transfers.
@@ -17,8 +18,17 @@ export function useTransfers() {
try {
const data = await listTransfers();
setTransfers(data);
- } catch {
- setError('Could not load transfers. Please try again.');
+ } catch (err) {
+ if (err instanceof ContractViolationError) {
+ // A schema change, not a flaky request. Retrying will not help, and
+ // showing an empty list would imply the transfers no longer exist.
+ console.error(err.message);
+ setError(
+ `Your transfers could not be displayed: the data did not match the expected format (${err.contract}). Nothing has been lost — please try again shortly.`,
+ );
+ } else {
+ setError('Could not load transfers. Please try again.');
+ }
} finally {
setLoading(false);
}
diff --git a/src/pages/SendMoney.jsx b/src/pages/SendMoney.jsx
index 344b26c..8c6a037 100644
--- a/src/pages/SendMoney.jsx
+++ b/src/pages/SendMoney.jsx
@@ -6,6 +6,7 @@ import QuoteCard from '../components/QuoteCard.jsx';
import Button from '../components/Button.jsx';
import ErrorMessage from '../components/ErrorMessage.jsx';
import { buildQuote } from '../services/quote.js';
+import { ContractViolationError } from '../services/contracts/schema.js';
import { formatCurrencyInput } from '../utils/format.js';
import {
isPositiveAmount,
@@ -100,18 +101,40 @@ export default function SendMoney() {
// Build from the live amount so a pending debounce can't submit a stale quote.
const finalQuote = buildQuote(amount, from, to);
- if (!finalQuote) return;
+ if (!finalQuote) {
+ // Previously this returned silently, leaving the user on an enabled
+ // button with no explanation of why nothing happened.
+ setSubmitError(
+ 'We could not price this transfer. Check the amount and the selected currencies.',
+ );
+ return;
+ }
+ // Record the fee, rate and expiry alongside the amounts so the receipt
+ // can reproduce exactly what was quoted rather than re-deriving it from
+ // a rate that may since have moved.
await addTransfer({
recipient,
from,
to,
sendAmount: finalQuote.sendAmount,
receiveAmount: finalQuote.receiveAmount,
+ fee: finalQuote.fee,
+ rate: finalQuote.rate,
+ expiresAt: finalQuote.expiresAt,
});
navigate('/transfers');
} catch (err) {
- setSubmitError('Could not submit the transfer. Please try again.');
+ if (err instanceof ContractViolationError) {
+ // The full field-by-field diff goes to the console; the user gets a
+ // message that distinguishes "we rejected this" from "try again".
+ console.error(err.message);
+ setSubmitError(
+ 'This transfer was rejected before it was sent because the details did not match the expected format. Nothing was submitted.',
+ );
+ } else {
+ setSubmitError('Could not submit the transfer. Please try again.');
+ }
} finally {
submissionLock.current = false;
setSubmitting(false);
diff --git a/src/pages/Transfers.jsx b/src/pages/Transfers.jsx
index 2967fe8..91e1f90 100644
--- a/src/pages/Transfers.jsx
+++ b/src/pages/Transfers.jsx
@@ -1,8 +1,13 @@
import { useCallback, useEffect, useMemo, useState } from 'react';
import { Link, useSearchParams } from 'react-router-dom';
import Chart from '../components/Chart.jsx';
-import { formatAmount } from '../utils/format.js';
+import { formatMoney, parseDecimal } from '../utils/money.js';
+import {
+ TRANSFER_STATUSES,
+ normalizeStatus,
+} from '../services/contracts/transfer.js';
import TransferRow from '../components/TransferRow.jsx';
+import { TRANSFER_STATUS_LABELS } from '../components/StatusBadge.jsx';
import Skeleton from '../components/Skeleton.jsx';
import ErrorMessage from '../components/ErrorMessage.jsx';
import EmptyState from '../components/EmptyState.jsx';
@@ -15,11 +20,14 @@ import { useApp } from '../context/AppContext.jsx';
import { DATE_RANGE_PRESETS, isWithinDateRange } from '../utils/dateRange.js';
import './Transfers.css';
+// Derived from the contract so a new lifecycle state cannot be filterable in
+// the data but missing from the dropdown.
const STATUS_OPTIONS = [
{ value: '', label: 'All statuses' },
- { value: 'pending', label: 'Pending' },
- { value: 'completed', label: 'Completed' },
- { value: 'failed', label: 'Failed' },
+ ...TRANSFER_STATUSES.map((value) => ({
+ value,
+ label: TRANSFER_STATUS_LABELS[value],
+ })),
];
const PAGE_SIZE = 5;
@@ -51,15 +59,19 @@ export default function Transfers() {
setSelectAllAcross(false);
}, [search, status, range]);
+ // Normalise the query-string status so a legacy or provider spelling in a
+ // shared/bookmarked URL (?status=settled) still selects the right rows.
+ const canonicalStatus = normalizeStatus(status);
+
const filteredTransfers = useMemo(() => {
return transfers.filter((t) => {
- if (status && t.status !== status) return false;
+ if (status && normalizeStatus(t.status) !== canonicalStatus) return false;
if (search && !t.recipient.toLowerCase().includes(search.toLowerCase()))
return false;
if (!isWithinDateRange(t.createdAt, range)) return false;
return true;
});
- }, [transfers, search, status, range]);
+ }, [transfers, search, status, canonicalStatus, range]);
// Paginated data
const totalPages = Math.ceil(filteredTransfers.length / PAGE_SIZE) || 1;
@@ -210,12 +222,17 @@ export default function Transfers() {
({
- value: parseFloat(t.sendAmount),
- label: t.recipient,
- currency: t.from,
- }))}
- formatValue={(d) => formatAmount(d.value, d.currency)}
+ data={filteredTransfers.slice(0, 5).map((t) => {
+ // Bar heights need a float; the label keeps the exact decimal.
+ const parsed = parseDecimal(t.sendAmount);
+ return {
+ value: parsed.ok ? Number(parsed.value) : 0,
+ amount: parsed.ok ? parsed.value : null,
+ label: t.recipient,
+ currency: t.from,
+ };
+ })}
+ formatValue={(d) => formatMoney(d.amount, d.currency)}
/>
{pageTransfers.map((t) => (
} rejected
+ */
+function reportRejected(rejected) {
+ for (const entry of rejected) {
+ console.error(entry.diff);
+ }
+}
+
/**
* List all transfers, newest first.
- * @returns {Promise}
+ *
+ * One malformed record is dropped and logged so the rest of the list still
+ * renders. A response where *every* record fails is a schema change, not bad
+ * data, and is raised so the UI can say so instead of showing "no transfers".
+ *
+ * @returns {Promise} contract-normalised transfers
*/
export function listTransfers() {
- return new Promise((resolve) => {
+ return new Promise((resolve, reject) => {
setTimeout(() => {
- const transfers = read()
- .slice()
- .sort((a, b) => {
- return new Date(b.createdAt) - new Date(a.createdAt);
+ try {
+ const { transfers, rejected, breaking } = parseTransferList(read(), {
+ source: 'listTransfers',
});
- resolve(transfers);
+ if (breaking) {
+ // Every row failed: raise one aggregate error carrying all the
+ // issues. Reporting each row here as well would log the same diff
+ // twice, since the caller logs whatever it catches.
+ throw new ContractViolationError(
+ transferContract,
+ rejected.flatMap((entry) => entry.issues),
+ { source: 'listTransfers' },
+ );
+ }
+ if (rejected.length) reportRejected(rejected);
+ resolve(
+ transfers
+ .slice()
+ .sort((a, b) => new Date(b.createdAt) - new Date(a.createdAt)),
+ );
+ } catch (error) {
+ reject(error);
+ }
}, 400);
});
}
/**
* Create a new transfer record.
+ *
+ * The assembled record is validated before it is persisted, so a drifted
+ * payload fails at submission with an actionable diff instead of writing a
+ * record that later renders as a plausible-looking wrong number.
+ *
* @param {object} payload - transfer details
* @returns {Promise} the created transfer
*/
export function createTransfer(payload) {
- return new Promise((resolve) => {
+ return new Promise((resolve, reject) => {
setTimeout(() => {
- const transfer = {
- id: 'tx_' + Date.now(),
- status: 'pending',
- createdAt: new Date().toISOString(),
- ...payload,
- };
- const transfers = read();
- transfers.push(transfer);
- write(transfers);
- resolve(transfer);
+ try {
+ const transfer = parseTransfer(
+ {
+ id: 'tx_' + Date.now(),
+ status: 'pending',
+ createdAt: new Date().toISOString(),
+ ...payload,
+ },
+ { source: 'createTransfer' },
+ );
+ const existing = read();
+ const transfers = Array.isArray(existing) ? existing : [];
+ transfers.push(transfer);
+ write(transfers);
+ resolve(transfer);
+ } catch (error) {
+ reject(error);
+ }
}, 700);
});
}
diff --git a/src/services/contracts/README.md b/src/services/contracts/README.md
new file mode 100644
index 0000000..c24666a
--- /dev/null
+++ b/src/services/contracts/README.md
@@ -0,0 +1,49 @@
+# API contracts
+
+Every response the app reads is validated here before anything renders it. The
+goal is not validation for its own sake — it is that a schema or precision
+change from the provider **fails loudly with a diff you can act on**, instead of
+quietly becoming a `$0.00` on someone's receipt.
+
+## Layout
+
+| File | Purpose |
+| ------------- | --------------------------------------------------------------- |
+| `schema.js` | The validator: field types, issue codes, and the diff formatter |
+| `transfer.js` | `Transfer v1` — the record the transfers list and rows render |
+| `quote.js` | `Quote v1` — the priced transfer shown before submission |
+
+Recorded payloads live in `test/fixtures/v/`, with the ones that must be
+rejected in `test/fixtures/v/breaking/`.
+
+## What counts as breaking
+
+- **Additive** — a provider adds a field. Allowed and preserved, so a released
+ client keeps working.
+- **Breaking** — a declared field is missing, renamed, retyped, or carries a
+ value outside its declared set. Rejected with a diff naming the field.
+
+A snake_case rename is reported as `renamed_field` rather than as an unrelated
+missing field, so the diff points at the actual change:
+
+```
+Transfer v1 contract mismatch from listTransfers[0] (1 issue):
+ - sendAmount: expected field "sendAmount", received field "send_amount" carrying string "200.00"
+ hint: "send_amount" looks like a renamed "sendAmount" — map it in the adapter or bump the contract version
+ Fix: update the adapter for Transfer v1 and the matching fixtures in test/fixtures/v1/ together, or bump the contract version.
+```
+
+## Changing a contract
+
+1. Decide whether the change is additive (no version bump) or breaking.
+2. For a breaking change, add `test/fixtures/v/`, keeping `v` intact so
+ the old shape stays covered while both are in flight.
+3. Update the schema and the fixtures **in the same commit**. The contract tests
+ fail if a declared status has no fixture, or if a breaking fixture has no
+ recorded expectation, so neither half can be forgotten.
+
+## Money
+
+Amounts cross this boundary as canonical decimal _strings_ and are never
+floats in between — see the header of `src/utils/money.js` for why. Render them
+with `formatMoney`, not `formatAmount`.
diff --git a/src/services/contracts/quote.js b/src/services/contracts/quote.js
new file mode 100644
index 0000000..3ca0cb9
--- /dev/null
+++ b/src/services/contracts/quote.js
@@ -0,0 +1,51 @@
+// Versioned contract for an FX quote.
+//
+// Amounts are decimal strings, not floats: a quote is a promise about exact
+// numbers, and the receipt has to be able to reproduce them.
+
+import { defineContract, parseOrThrow } from './schema.js';
+
+export const QUOTE_CONTRACT_VERSION = 1;
+
+/** How long a quote is honoured before it must be rebuilt. */
+export const QUOTE_TTL_MS = 60_000;
+
+export const quoteContract = defineContract({
+ name: 'Quote',
+ version: QUOTE_CONTRACT_VERSION,
+ fields: {
+ version: { type: 'integer', required: true },
+ from: { type: 'currency', required: true },
+ to: { type: 'currency', required: true },
+ rate: { type: 'decimal', required: true, min: 0 },
+ sendAmount: { type: 'decimal', required: true, min: 0 },
+ fee: { type: 'decimal', required: true, min: 0 },
+ amountAfterFee: { type: 'decimal', required: true, min: 0 },
+ receiveAmount: { type: 'decimal', required: true, min: 0 },
+ createdAt: { type: 'timestamp', required: true },
+ expiresAt: { type: 'timestamp', required: true },
+ },
+});
+
+/**
+ * Parse a quote payload, throwing an actionable diff if it does not match v1.
+ * @param {unknown} raw
+ * @param {{source?: string}} [options]
+ * @returns {object}
+ */
+export function parseQuote(raw, options = {}) {
+ return parseOrThrow(quoteContract, raw, options);
+}
+
+/**
+ * Has a quote passed its expiry?
+ * @param {object} quote - a parsed quote
+ * @param {number|Date} [now] - injectable clock, so tests stay deterministic
+ * @returns {boolean}
+ */
+export function isQuoteExpired(quote, now = Date.now()) {
+ if (!quote?.expiresAt) return false;
+ const expiry = Date.parse(quote.expiresAt);
+ if (Number.isNaN(expiry)) return true;
+ return (now instanceof Date ? now.getTime() : now) >= expiry;
+}
diff --git a/src/services/contracts/schema.js b/src/services/contracts/schema.js
new file mode 100644
index 0000000..cc15c1c
--- /dev/null
+++ b/src/services/contracts/schema.js
@@ -0,0 +1,311 @@
+// A tiny, dependency-free schema validator for API responses.
+//
+// The point is not general-purpose validation — it is *actionable failure*.
+// When a provider renames a field or changes a type, the app should say
+// exactly which field moved and what it moved to, instead of quietly
+// rendering a zero. Every issue carries the path, what was expected and what
+// actually arrived, and `formatIssues` turns that into a diff a reviewer can
+// act on without opening a debugger.
+//
+// Compatibility policy, applied by `validate`:
+// * unknown fields are ALLOWED and preserved — providers may add fields
+// without breaking a released client (forward compatible);
+// * missing, retyped or renamed declared fields are BREAKING and reported.
+
+import {
+ compareDecimal,
+ describeValue,
+ parseDecimal,
+} from '../../utils/money.js';
+
+/** @typedef {{path: string, code: string, expected: string, received: string, hint?: string}} ContractIssue */
+
+const CURRENCY_PATTERN = /^[A-Z]{3}$/;
+
+/**
+ * Normalise a field name so that `send_amount`, `sendAmount` and `SendAmount`
+ * collapse to the same key. Used to detect renames rather than reporting them
+ * as an unrelated "missing field".
+ * @param {string} key
+ * @returns {string}
+ */
+function normalizeKey(key) {
+ return key.toLowerCase().replace(/[_\-\s]/g, '');
+}
+
+const VALIDATORS = {
+ string(value, field) {
+ if (typeof value !== 'string') {
+ return { expected: 'string', received: describeValue(value) };
+ }
+ if (field.pattern && !field.pattern.test(value)) {
+ return {
+ expected: `string matching ${field.pattern}`,
+ received: describeValue(value),
+ };
+ }
+ if (field.minLength && value.length < field.minLength) {
+ return {
+ expected: `string of at least ${field.minLength} characters`,
+ received: describeValue(value),
+ };
+ }
+ return { value };
+ },
+
+ currency(value) {
+ if (typeof value !== 'string' || !CURRENCY_PATTERN.test(value)) {
+ return {
+ expected: 'ISO 4217 currency code (three uppercase letters)',
+ received: describeValue(value),
+ };
+ }
+ return { value };
+ },
+
+ // Money and rates. Normalised to a canonical decimal *string* so no float
+ // ever enters the app from a response body.
+ decimal(value, field) {
+ const parsed = parseDecimal(value);
+ if (!parsed.ok) {
+ return {
+ expected: 'decimal (number or numeric string)',
+ received: describeValue(value),
+ hint: parsed.error,
+ };
+ }
+ if (field.min != null && compareDecimal(parsed.value, field.min) < 0) {
+ return {
+ expected: `decimal >= ${field.min}`,
+ received: describeValue(value),
+ };
+ }
+ return { value: parsed.value };
+ },
+
+ integer(value) {
+ if (typeof value !== 'number' || !Number.isSafeInteger(value)) {
+ return {
+ expected: 'safe integer',
+ received: describeValue(value),
+ };
+ }
+ return { value };
+ },
+
+ boolean(value) {
+ if (typeof value !== 'boolean') {
+ return { expected: 'boolean', received: describeValue(value) };
+ }
+ return { value };
+ },
+
+ timestamp(value) {
+ if (typeof value !== 'string' || Number.isNaN(Date.parse(value))) {
+ return {
+ expected: 'ISO 8601 timestamp string',
+ received: describeValue(value),
+ };
+ }
+ return { value };
+ },
+
+ enum(value, field) {
+ if (typeof value !== 'string') {
+ return {
+ expected: `one of [${field.values.join(', ')}]`,
+ received: describeValue(value),
+ };
+ }
+ if (field.values.includes(value)) return { value };
+
+ const aliased = field.aliases?.[value];
+ if (aliased && field.values.includes(aliased)) {
+ // A known legacy spelling: accept it and normalise, no issue raised.
+ return { value: aliased };
+ }
+ return {
+ expected: `one of [${field.values.join(', ')}]`,
+ received: describeValue(value),
+ hint: field.aliases
+ ? `accepted legacy spellings: ${Object.keys(field.aliases).join(', ')}`
+ : undefined,
+ };
+ },
+};
+
+/**
+ * Declare a versioned contract.
+ * @param {{name: string, version: number, fields: object}} definition
+ * @returns {{name: string, version: number, fields: object, id: string}}
+ */
+export function defineContract(definition) {
+ const { name, version, fields } = definition;
+ for (const [key, field] of Object.entries(fields)) {
+ if (!VALIDATORS[field.type]) {
+ throw new Error(
+ `Contract ${name} v${version}: field "${key}" uses unknown type "${field.type}"`,
+ );
+ }
+ }
+ return { ...definition, id: `${name} v${version}` };
+}
+
+/**
+ * Validate a raw response object against a contract.
+ *
+ * @param {object} contract - from defineContract()
+ * @param {unknown} raw - the value straight off the wire
+ * @returns {{ok: boolean, value: object|null, issues: ContractIssue[]}}
+ */
+export function validate(contract, raw) {
+ if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+ return {
+ ok: false,
+ value: null,
+ issues: [
+ {
+ path: '(root)',
+ code: 'not_an_object',
+ expected: 'object',
+ received: describeValue(raw),
+ },
+ ],
+ };
+ }
+
+ const issues = [];
+ const result = {};
+ const declaredKeys = Object.keys(contract.fields);
+ const unknownKeys = Object.keys(raw).filter((k) => !declaredKeys.includes(k));
+
+ // Index unknown keys by normalised name so a rename is reported as a rename.
+ const unknownByNormalized = new Map();
+ for (const key of unknownKeys) {
+ unknownByNormalized.set(normalizeKey(key), key);
+ }
+
+ for (const [key, field] of Object.entries(contract.fields)) {
+ const present = Object.prototype.hasOwnProperty.call(raw, key);
+ const value = raw[key];
+
+ if (
+ !present ||
+ value === undefined ||
+ (value === null && !field.nullable)
+ ) {
+ if (field.required) {
+ const renamedFrom = unknownByNormalized.get(normalizeKey(key));
+ if (renamedFrom) {
+ issues.push({
+ path: key,
+ code: 'renamed_field',
+ expected: `field "${key}"`,
+ received: `field "${renamedFrom}" carrying ${describeValue(raw[renamedFrom])}`,
+ hint: `"${renamedFrom}" looks like a renamed "${key}" — map it in the adapter or bump the contract version`,
+ });
+ } else {
+ issues.push({
+ path: key,
+ code: 'missing_field',
+ expected: `required ${field.type}`,
+ received: present ? describeValue(value) : 'absent',
+ });
+ }
+ continue;
+ }
+ if (field.default !== undefined) result[key] = field.default;
+ else if (value === null && field.nullable) result[key] = null;
+ continue;
+ }
+
+ if (value === null && field.nullable) {
+ result[key] = null;
+ continue;
+ }
+
+ const outcome = VALIDATORS[field.type](value, field);
+ if (outcome.expected) {
+ issues.push({
+ path: key,
+ code: field.type === 'enum' ? 'invalid_enum' : 'wrong_type',
+ expected: outcome.expected,
+ received: outcome.received,
+ hint: outcome.hint,
+ });
+ continue;
+ }
+ result[key] = outcome.value;
+ }
+
+ // Unknown fields are forward-compatible: keep them, never fail on them.
+ for (const key of unknownKeys) {
+ if (!(key in result)) result[key] = raw[key];
+ }
+
+ return {
+ ok: issues.length === 0,
+ value: issues.length ? null : result,
+ issues,
+ };
+}
+
+/**
+ * Render issues as a multi-line, actionable diff.
+ * @param {object} contract
+ * @param {ContractIssue[]} issues
+ * @param {{source?: string}} [options] - where the payload came from
+ * @returns {string}
+ */
+export function formatIssues(contract, issues, options = {}) {
+ const source = options.source ? ` from ${options.source}` : '';
+ const lines = [
+ `${contract.id} contract mismatch${source} (${issues.length} ${
+ issues.length === 1 ? 'issue' : 'issues'
+ }):`,
+ ];
+ for (const issue of issues) {
+ lines.push(
+ ` - ${issue.path}: expected ${issue.expected}, received ${issue.received}`,
+ );
+ if (issue.hint) lines.push(` hint: ${issue.hint}`);
+ }
+ lines.push(
+ ` Fix: update the adapter for ${contract.id} and the matching fixtures in test/fixtures/v${contract.version}/ together, or bump the contract version.`,
+ );
+ return lines.join('\n');
+}
+
+/**
+ * Thrown when a payload cannot be trusted. The message is the actionable diff;
+ * `issues` is the structured form for tests and telemetry.
+ */
+export class ContractViolationError extends Error {
+ /**
+ * @param {object} contract
+ * @param {ContractIssue[]} issues
+ * @param {{source?: string}} [options]
+ */
+ constructor(contract, issues, options = {}) {
+ super(formatIssues(contract, issues, options));
+ this.name = 'ContractViolationError';
+ this.contract = contract.id;
+ this.version = contract.version;
+ this.issues = issues;
+ this.source = options.source;
+ }
+}
+
+/**
+ * Validate or throw a ContractViolationError carrying the diff.
+ * @param {object} contract
+ * @param {unknown} raw
+ * @param {{source?: string}} [options]
+ * @returns {object} the normalised value
+ */
+export function parseOrThrow(contract, raw, options = {}) {
+ const outcome = validate(contract, raw);
+ if (!outcome.ok)
+ throw new ContractViolationError(contract, outcome.issues, options);
+ return outcome.value;
+}
diff --git a/src/services/contracts/transfer.js b/src/services/contracts/transfer.js
new file mode 100644
index 0000000..ce4e901
--- /dev/null
+++ b/src/services/contracts/transfer.js
@@ -0,0 +1,155 @@
+// Versioned contract for a transfer record.
+//
+// v1 is the shape RemitFlow's UI renders. Anything reaching the app through
+// `parseTransfer` has already been checked field by field, so the receipt
+// screens can render without defensive coercion.
+
+import {
+ ContractViolationError,
+ defineContract,
+ formatIssues,
+ parseOrThrow,
+ validate,
+} from './schema.js';
+
+export const TRANSFER_CONTRACT_VERSION = 1;
+
+/**
+ * The transfer lifecycle, in order. `completed` is the settled terminal state;
+ * it keeps its historical name because it is what the UI, the URL query string
+ * (`?status=completed`) and every stored record already use.
+ */
+export const TRANSFER_STATUSES = [
+ 'quoted',
+ 'validating',
+ 'authorizing',
+ 'pending',
+ 'completed',
+ 'failed',
+ 'expired',
+];
+
+/**
+ * Wire spellings accepted from a provider and normalised on the way in.
+ * Adding an entry here is a compatibility fix; removing one is breaking.
+ */
+export const TRANSFER_STATUS_ALIASES = {
+ settled: 'completed',
+ succeeded: 'completed',
+ success: 'completed',
+ submitted: 'pending',
+ processing: 'pending',
+ validation_pending: 'validating',
+ authorization_required: 'authorizing',
+};
+
+/** Statuses that will not change again. */
+export const TERMINAL_STATUSES = ['completed', 'failed', 'expired'];
+
+export const transferContract = defineContract({
+ name: 'Transfer',
+ version: TRANSFER_CONTRACT_VERSION,
+ fields: {
+ id: { type: 'string', required: true, minLength: 1 },
+ recipient: { type: 'string', required: true, minLength: 1 },
+ from: { type: 'currency', required: true },
+ to: { type: 'currency', required: true },
+ sendAmount: { type: 'decimal', required: true, min: 0 },
+ receiveAmount: { type: 'decimal', required: true, min: 0 },
+ status: {
+ type: 'enum',
+ required: true,
+ values: TRANSFER_STATUSES,
+ aliases: TRANSFER_STATUS_ALIASES,
+ },
+ createdAt: { type: 'timestamp', required: true },
+ // Optional enrichment. Absent on legacy records, so never required.
+ fee: { type: 'decimal', required: false, min: 0 },
+ rate: { type: 'decimal', required: false, min: 0 },
+ expiresAt: { type: 'timestamp', required: false },
+ failureReason: { type: 'string', required: false, nullable: true },
+ },
+});
+
+/**
+ * Parse one transfer, throwing an actionable diff if it does not match v1.
+ * @param {unknown} raw
+ * @param {{source?: string}} [options]
+ * @returns {object} normalised transfer (amounts are decimal strings)
+ */
+export function parseTransfer(raw, options = {}) {
+ return parseOrThrow(transferContract, raw, options);
+}
+
+/**
+ * Parse a list of transfers without letting one bad record hide the rest.
+ *
+ * A single corrupt row is a data problem: drop it and carry on. Every row
+ * failing is a schema change: that is reported through `breaking` so callers
+ * can surface it instead of rendering a convincing empty state.
+ *
+ * @param {unknown} raw - the response body
+ * @param {{source?: string}} [options]
+ * @returns {{transfers: object[], rejected: Array<{index: number, issues: object[], diff: string}>, breaking: boolean}}
+ */
+export function parseTransferList(raw, options = {}) {
+ if (!Array.isArray(raw)) {
+ throw new ContractViolationError(
+ transferContract,
+ [
+ {
+ path: '(root)',
+ code: 'not_an_array',
+ expected: 'array of Transfer',
+ received: raw === null ? 'null' : typeof raw,
+ },
+ ],
+ options,
+ );
+ }
+
+ const transfers = [];
+ const rejected = [];
+
+ raw.forEach((item, index) => {
+ const outcome = validate(transferContract, item);
+ if (outcome.ok) {
+ transfers.push(outcome.value);
+ return;
+ }
+ rejected.push({
+ index,
+ issues: outcome.issues,
+ diff: formatIssues(transferContract, outcome.issues, {
+ source: `${options.source ?? 'response'}[${index}]`,
+ }),
+ });
+ });
+
+ return {
+ transfers,
+ rejected,
+ breaking: raw.length > 0 && transfers.length === 0,
+ };
+}
+
+/**
+ * Normalise a status string the way the contract does, for callers that hold
+ * a bare status (a URL query parameter, a filter dropdown) rather than a
+ * whole record.
+ * @param {string} status
+ * @returns {string|null} canonical status, or null if unrecognised
+ */
+export function normalizeStatus(status) {
+ if (typeof status !== 'string') return null;
+ if (TRANSFER_STATUSES.includes(status)) return status;
+ return TRANSFER_STATUS_ALIASES[status] ?? null;
+}
+
+/**
+ * @param {string} status
+ * @returns {boolean}
+ */
+export function isTerminalStatus(status) {
+ return TERMINAL_STATUSES.includes(normalizeStatus(status));
+}
diff --git a/src/services/fx.js b/src/services/fx.js
index 1d6d8da..a38a24e 100644
--- a/src/services/fx.js
+++ b/src/services/fx.js
@@ -1,28 +1,64 @@
// Mock FX rate service. In production these rates would come from the backend
// or an on-chain Stellar DEX path-payment quote.
+//
+// Rates are held as decimal *strings* and cross rates are derived by exact
+// decimal division. Quoting EUR->NGN as `1480.5 / 0.92` in binary floating
+// point yields 1609.2391304347825, which is already wrong in the last place;
+// at NGN scale that error is visible on a receipt.
+
+import { divideDecimal, parseDecimal } from '../utils/money.js';
// Rates expressed relative to 1 USD.
const USD_RATES = {
- USD: 1,
- EUR: 0.92,
- GBP: 0.79,
- NGN: 1480.5,
- INR: 83.2,
- PHP: 58.4,
- MXN: 17.1,
+ USD: '1',
+ EUR: '0.92',
+ GBP: '0.79',
+ NGN: '1480.5',
+ INR: '83.2',
+ PHP: '58.4',
+ MXN: '17.1',
};
-export function getRate(from, to) {
+/**
+ * Cross rate as an exact decimal string: units of `to` per 1 unit of `from`.
+ * @param {string} from - source currency code
+ * @param {string} to - destination currency code
+ * @returns {string|null} decimal string, or null when the pair is unsupported
+ */
+export function getRateDecimal(from, to) {
const fromRate = USD_RATES[from];
const toRate = USD_RATES[to];
if (!fromRate || !toRate) return null;
- return toRate / fromRate;
+ if (from === to) return '1';
+ return divideDecimal(toRate, fromRate);
+}
+
+/**
+ * Cross rate as a number. Convenient for display and charting; do not use it
+ * for money arithmetic — use getRateDecimal() with the helpers in utils/money.
+ * @param {string} from
+ * @param {string} to
+ * @returns {number|null}
+ */
+export function getRate(from, to) {
+ const decimal = getRateDecimal(from, to);
+ return decimal == null ? null : Number(decimal);
}
+/**
+ * Convert an amount between currencies.
+ * @param {number|string} amount
+ * @param {string} from
+ * @param {string} to
+ * @returns {number|null} null when the pair is unsupported or the amount is
+ * not a parseable decimal — never a silently coerced zero
+ */
export function convert(amount, from, to) {
- const rate = getRate(from, to);
+ const rate = getRateDecimal(from, to);
if (rate == null) return null;
- return Number(amount) * rate;
+ const parsed = parseDecimal(amount);
+ if (!parsed.ok) return null;
+ return Number(parsed.value) * Number(rate);
}
/**
diff --git a/src/services/quote.js b/src/services/quote.js
index 479497b..dbec364 100644
--- a/src/services/quote.js
+++ b/src/services/quote.js
@@ -1,42 +1,100 @@
// Quote service: combines FX rates and fees into a full transfer quote.
-import { getRate, convert } from './fx.js';
+//
+// All arithmetic runs on integer minor units. The old implementation chained
+// float operations (percentOf -> roundTo -> subtract -> multiply), so the
+// receive amount carried accumulated binary error and the stored value did not
+// always equal the quoted one. Here every intermediate is exact and every
+// output is quantized to the real minor unit of its currency.
+
+import { getRateDecimal } from './fx.js';
import { FEE_PERCENT, FLAT_FEE, MIN_FEE } from '../constants/fees.js';
-import { percentOf, roundTo } from '../utils/math.js';
+import {
+ QUOTE_CONTRACT_VERSION,
+ QUOTE_TTL_MS,
+ parseQuote,
+} from './contracts/quote.js';
+import {
+ convertMinorUnits,
+ currencyExponent,
+ fromMinorUnits,
+ parseDecimal,
+ scaleMinorUnits,
+ toMinorUnits,
+} from '../utils/money.js';
/**
* Calculate the total fee (in the source currency) for a given send amount.
- * @param {number} amount - amount being sent in the source currency
- * @returns {number} the fee in the source currency
+ * @param {number|string} amount - amount being sent in the source currency
+ * @param {string} [currency] - source currency, for minor-unit precision
+ * @returns {string|null} fee as a decimal string, or null if `amount` is not
+ * a parseable decimal
*/
-export function calculateFee(amount) {
- const num = Number(amount) || 0;
- const fee = percentOf(num, FEE_PERCENT) + FLAT_FEE;
- return roundTo(Math.max(fee, MIN_FEE));
+export function calculateFee(amount, currency = 'USD') {
+ const parsed = parseDecimal(amount);
+ if (!parsed.ok) return null;
+
+ const exponent = currencyExponent(currency);
+ const sendMinor = toMinorUnits(parsed.value, exponent);
+ const percentMinor = scaleMinorUnits(sendMinor, FEE_PERCENT);
+ const flatMinor = toMinorUnits(FLAT_FEE, exponent);
+ const minMinor = toMinorUnits(MIN_FEE, exponent);
+
+ const feeMinor = percentMinor + flatMinor;
+ return fromMinorUnits(feeMinor > minMinor ? feeMinor : minMinor, exponent);
}
/**
* Build a full quote for a transfer.
- * @param {number} amount - amount to send in the source currency
+ *
+ * @param {number|string} amount - amount to send in the source currency
* @param {string} from - source currency code
* @param {string} to - destination currency code
- * @returns {object|null} quote breakdown or null if the pair is unsupported
+ * @param {{now?: number|Date, ttlMs?: number}} [options] - injectable clock so
+ * quote expiry is deterministic under test
+ * @returns {object|null} a Quote v1 payload, or null when the pair is
+ * unsupported or the amount is not a parseable decimal
*/
-export function buildQuote(amount, from, to) {
- const rate = getRate(from, to);
+export function buildQuote(amount, from, to, options = {}) {
+ const rate = getRateDecimal(from, to);
if (rate == null) return null;
- const sendAmount = Number(amount) || 0;
- const fee = calculateFee(sendAmount);
- const amountAfterFee = Math.max(sendAmount - fee, 0);
- const receiveAmount = convert(amountAfterFee, from, to);
+ const parsed = parseDecimal(amount);
+ if (!parsed.ok) return null;
- return {
- from,
- to,
+ const fromExponent = currencyExponent(from);
+ const toExponent = currencyExponent(to);
+
+ const sendMinor = toMinorUnits(parsed.value, fromExponent);
+ const feeMinor = toMinorUnits(calculateFee(parsed.value, from), fromExponent);
+ const afterFeeMinor = sendMinor > feeMinor ? sendMinor - feeMinor : 0n;
+ const receiveMinor = convertMinorUnits(
+ afterFeeMinor,
rate,
- sendAmount,
- fee,
- amountAfterFee,
- receiveAmount,
- };
+ fromExponent,
+ toExponent,
+ );
+
+ const nowMs =
+ options.now instanceof Date
+ ? options.now.getTime()
+ : (options.now ?? Date.now());
+ const ttlMs = options.ttlMs ?? QUOTE_TTL_MS;
+
+ // Round-trip through the contract so a quote is validated at the point it is
+ // produced, not only at the point it is consumed.
+ return parseQuote(
+ {
+ version: QUOTE_CONTRACT_VERSION,
+ from,
+ to,
+ rate,
+ sendAmount: fromMinorUnits(sendMinor, fromExponent),
+ fee: fromMinorUnits(feeMinor, fromExponent),
+ amountAfterFee: fromMinorUnits(afterFeeMinor, fromExponent),
+ receiveAmount: fromMinorUnits(receiveMinor, toExponent),
+ createdAt: new Date(nowMs).toISOString(),
+ expiresAt: new Date(nowMs + ttlMs).toISOString(),
+ },
+ { source: 'buildQuote' },
+ );
}
diff --git a/src/utils/format.js b/src/utils/format.js
index c8a61a7..8d5a3db 100644
--- a/src/utils/format.js
+++ b/src/utils/format.js
@@ -1,8 +1,15 @@
// Formatting helpers for currency, dates and addresses.
import { DEFAULT_LOCALE } from '../constants/locales.js';
+import { parseDecimal, quantize } from './money.js';
/**
* Format an amount as a currency string.
+ *
+ * Low-level helper: it assumes two decimal places and falls back to 0 for a
+ * non-numeric amount. For money that arrived from an API use `formatMoney`
+ * in utils/money.js instead, which honours the currency's real minor unit and
+ * refuses to render an unparseable value as "0.00".
+ *
* @param {number|string} amount - the amount to format
* @param {string} [currency] - ISO currency code, e.g. "USD"
* @param {string} [locale] - BCP 47 locale tag used for grouping, decimal
@@ -41,30 +48,47 @@ export function formatDate(value, locale = DEFAULT_LOCALE) {
/**
* Format an exchange rate as a "1 FROM = X TO" string.
- * @param {number} rate
+ * Accepts the decimal strings that the FX and quote services now produce as
+ * well as plain numbers; anything unparseable renders as "-".
+ * @param {number|string} rate
* @param {string} from
* @param {string} to
* @returns {string}
*/
export function formatRate(rate, from, to) {
- if (rate == null) return '-';
- return `1 ${from} = ${rate.toFixed(4)} ${to}`;
+ const parsed = parseDecimal(rate);
+ if (!parsed.ok) return '-';
+ return `1 ${from} = ${Number(parsed.value).toFixed(4)} ${to}`;
}
/**
- * Normalise a raw amount string into a clean, fixed-precision value.
- * Strips non-numeric characters and clamps to two decimal places so the
- * amount field shows a tidy value (e.g. "1,234.5" -> "1234.50").
- * @param {string} value - the raw input value
- * @returns {string} the cleaned amount, or '' if the input has no digits
+ * Normalise a raw amount string into a clean, fixed-precision value for the
+ * amount field (e.g. "1,234.5" -> "1234.50").
+ *
+ * The value is parsed first and only stripped of grouping characters as a
+ * fallback. Stripping first corrupts perfectly valid input: `/`, so a contract change has to be made in two places at
+// once: the schema and the recorded payloads. Fixtures are discovered from the
+// directory rather than listed here, so adding a state means adding a file and
+// nothing else — and deleting a state's fixture makes its test disappear
+// loudly rather than silently.
+//
+// v1/ payloads that MUST parse
+// v1/breaking/ payloads that MUST be rejected with an actionable diff
+//
+// Nothing here touches the network or the clock.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const FIXTURE_ROOT = path.dirname(fileURLToPath(import.meta.url));
+
+/** Contract versions with a recorded fixture set. */
+export const SUPPORTED_FIXTURE_VERSIONS = fs
+ .readdirSync(FIXTURE_ROOT, { withFileTypes: true })
+ .filter((entry) => entry.isDirectory() && /^v\d+$/.test(entry.name))
+ .map((entry) => Number(entry.name.slice(1)))
+ .sort((a, b) => a - b);
+
+function directoryFor(version, kind) {
+ return kind === 'breaking'
+ ? path.join(FIXTURE_ROOT, `v${version}`, 'breaking')
+ : path.join(FIXTURE_ROOT, `v${version}`);
+}
+
+/**
+ * List fixture names for a version.
+ * @param {number} version
+ * @param {{kind?: 'valid'|'breaking', prefix?: string}} [options]
+ * @returns {string[]} file names without the .json extension, sorted
+ */
+export function listFixtures(version, options = {}) {
+ const { kind = 'valid', prefix } = options;
+ const dir = directoryFor(version, kind);
+ return fs
+ .readdirSync(dir)
+ .filter((name) => name.endsWith('.json'))
+ .map((name) => name.replace(/\.json$/, ''))
+ .filter((name) => !prefix || name.startsWith(prefix))
+ .sort();
+}
+
+/**
+ * Read a fixture. Returns a fresh deep copy each call so a test that mutates
+ * a payload cannot leak into the next one.
+ * @param {number} version
+ * @param {string} name - fixture name without the .json extension
+ * @param {{kind?: 'valid'|'breaking'}} [options]
+ * @returns {object}
+ */
+export function loadFixture(version, name, options = {}) {
+ const kind = options.kind ?? 'valid';
+ const file = path.join(directoryFor(version, kind), `${name}.json`);
+ if (!fs.existsSync(file)) {
+ throw new Error(
+ `Fixture "${name}" not found for contract v${version} (${kind}). ` +
+ `Available: ${listFixtures(version, { kind }).join(', ')}`,
+ );
+ }
+ return JSON.parse(fs.readFileSync(file, 'utf8'));
+}
+
+function loadAll(version, options) {
+ return listFixtures(version, options).map((name) => ({
+ name,
+ payload: loadFixture(version, name, options),
+ }));
+}
+
+/**
+ * All valid transfer fixtures for a version.
+ * @param {number} version
+ * @returns {Array<{name: string, payload: object}>}
+ */
+export function loadTransferFixtures(version) {
+ return loadAll(version, { prefix: 'transfer.' });
+}
+
+/**
+ * All valid quote fixtures for a version.
+ * @param {number} version
+ * @returns {Array<{name: string, payload: object}>}
+ */
+export function loadQuoteFixtures(version) {
+ return loadAll(version, { prefix: 'quote.' });
+}
+
+/**
+ * All fixtures that must be rejected, for a version.
+ * @param {number} version
+ * @returns {Array<{name: string, payload: object}>}
+ */
+export function loadBreakingFixtures(version) {
+ return loadAll(version, { kind: 'breaking' });
+}
diff --git a/test/fixtures/v1/breaking/quote.formatted-rate.json b/test/fixtures/v1/breaking/quote.formatted-rate.json
new file mode 100644
index 0000000..57e1d28
--- /dev/null
+++ b/test/fixtures/v1/breaking/quote.formatted-rate.json
@@ -0,0 +1,12 @@
+{
+ "version": 1,
+ "from": "USD",
+ "to": "NGN",
+ "rate": "1,480.50",
+ "sendAmount": "200.00",
+ "fee": "1.10",
+ "amountAfterFee": "198.90",
+ "receiveAmount": "294471.45",
+ "createdAt": "2026-08-01T10:00:00Z",
+ "expiresAt": "2026-08-01T10:01:00Z"
+}
diff --git a/test/fixtures/v1/breaking/quote.missing-expiry.json b/test/fixtures/v1/breaking/quote.missing-expiry.json
new file mode 100644
index 0000000..c2d7ee2
--- /dev/null
+++ b/test/fixtures/v1/breaking/quote.missing-expiry.json
@@ -0,0 +1,11 @@
+{
+ "version": 1,
+ "from": "USD",
+ "to": "NGN",
+ "rate": "1480.5",
+ "sendAmount": "200.00",
+ "fee": "1.10",
+ "amountAfterFee": "198.90",
+ "receiveAmount": "294471.45",
+ "createdAt": "2026-08-01T10:00:00Z"
+}
diff --git a/test/fixtures/v1/breaking/transfer.epoch-timestamp.json b/test/fixtures/v1/breaking/transfer.epoch-timestamp.json
new file mode 100644
index 0000000..64b34a8
--- /dev/null
+++ b/test/fixtures/v1/breaking/transfer.epoch-timestamp.json
@@ -0,0 +1,10 @@
+{
+ "id": "tx_3005",
+ "recipient": "amina@example.com",
+ "from": "USD",
+ "to": "NGN",
+ "sendAmount": "200.00",
+ "receiveAmount": "294471.45",
+ "status": "pending",
+ "createdAt": 1785535200000
+}
diff --git a/test/fixtures/v1/breaking/transfer.money-object-amount.json b/test/fixtures/v1/breaking/transfer.money-object-amount.json
new file mode 100644
index 0000000..f6cc63f
--- /dev/null
+++ b/test/fixtures/v1/breaking/transfer.money-object-amount.json
@@ -0,0 +1,10 @@
+{
+ "id": "tx_3002",
+ "recipient": "amina@example.com",
+ "from": "USD",
+ "to": "NGN",
+ "sendAmount": { "value": "200.00", "currency": "USD" },
+ "receiveAmount": { "value": "294471.45", "currency": "NGN" },
+ "status": "pending",
+ "createdAt": "2026-08-01T10:00:00Z"
+}
diff --git a/test/fixtures/v1/breaking/transfer.non-iso-currency.json b/test/fixtures/v1/breaking/transfer.non-iso-currency.json
new file mode 100644
index 0000000..57544be
--- /dev/null
+++ b/test/fixtures/v1/breaking/transfer.non-iso-currency.json
@@ -0,0 +1,10 @@
+{
+ "id": "tx_3006",
+ "recipient": "amina@example.com",
+ "from": "usd",
+ "to": "NGN",
+ "sendAmount": "200.00",
+ "receiveAmount": "294471.45",
+ "status": "pending",
+ "createdAt": "2026-08-01T10:00:00Z"
+}
diff --git a/test/fixtures/v1/breaking/transfer.null-amount.json b/test/fixtures/v1/breaking/transfer.null-amount.json
new file mode 100644
index 0000000..25b952e
--- /dev/null
+++ b/test/fixtures/v1/breaking/transfer.null-amount.json
@@ -0,0 +1,10 @@
+{
+ "id": "tx_3004",
+ "recipient": "amina@example.com",
+ "from": "USD",
+ "to": "NGN",
+ "sendAmount": null,
+ "receiveAmount": "294471.45",
+ "status": "pending",
+ "createdAt": "2026-08-01T10:00:00Z"
+}
diff --git a/test/fixtures/v1/breaking/transfer.renamed-amount.json b/test/fixtures/v1/breaking/transfer.renamed-amount.json
new file mode 100644
index 0000000..d1634fc
--- /dev/null
+++ b/test/fixtures/v1/breaking/transfer.renamed-amount.json
@@ -0,0 +1,10 @@
+{
+ "id": "tx_3001",
+ "recipient": "amina@example.com",
+ "from": "USD",
+ "to": "NGN",
+ "send_amount": "200.00",
+ "receiveAmount": "294471.45",
+ "status": "pending",
+ "createdAt": "2026-08-01T10:00:00Z"
+}
diff --git a/test/fixtures/v1/breaking/transfer.unknown-status.json b/test/fixtures/v1/breaking/transfer.unknown-status.json
new file mode 100644
index 0000000..ebe69c1
--- /dev/null
+++ b/test/fixtures/v1/breaking/transfer.unknown-status.json
@@ -0,0 +1,10 @@
+{
+ "id": "tx_3003",
+ "recipient": "amina@example.com",
+ "from": "USD",
+ "to": "NGN",
+ "sendAmount": "200.00",
+ "receiveAmount": "294471.45",
+ "status": "in_flight",
+ "createdAt": "2026-08-01T10:00:00Z"
+}
diff --git a/test/fixtures/v1/quote.cross-rate.json b/test/fixtures/v1/quote.cross-rate.json
new file mode 100644
index 0000000..f829730
--- /dev/null
+++ b/test/fixtures/v1/quote.cross-rate.json
@@ -0,0 +1,12 @@
+{
+ "version": 1,
+ "from": "EUR",
+ "to": "NGN",
+ "rate": "1609.239130434783",
+ "sendAmount": "100.00",
+ "fee": "0.60",
+ "amountAfterFee": "99.40",
+ "receiveAmount": "159958.37",
+ "createdAt": "2026-08-01T10:00:00Z",
+ "expiresAt": "2026-08-01T10:01:00Z"
+}
diff --git a/test/fixtures/v1/quote.json b/test/fixtures/v1/quote.json
new file mode 100644
index 0000000..36da44b
--- /dev/null
+++ b/test/fixtures/v1/quote.json
@@ -0,0 +1,12 @@
+{
+ "version": 1,
+ "from": "USD",
+ "to": "NGN",
+ "rate": "1480.5",
+ "sendAmount": "200.00",
+ "fee": "1.10",
+ "amountAfterFee": "198.90",
+ "receiveAmount": "294471.45",
+ "createdAt": "2026-08-01T10:00:00Z",
+ "expiresAt": "2026-08-01T10:01:00Z"
+}
diff --git a/test/fixtures/v1/transfer.authorizing.json b/test/fixtures/v1/transfer.authorizing.json
new file mode 100644
index 0000000..cef6fac
--- /dev/null
+++ b/test/fixtures/v1/transfer.authorizing.json
@@ -0,0 +1,12 @@
+{
+ "id": "tx_2003",
+ "recipient": "GBQAZ7Z3X7DEMOPUBLICKEY4REMITFLOWWALLET123456789ABCDEF",
+ "from": "USD",
+ "to": "INR",
+ "sendAmount": "120.00",
+ "receiveAmount": "9925.76",
+ "fee": "0.70",
+ "rate": "83.2",
+ "status": "authorizing",
+ "createdAt": "2026-08-01T10:00:10Z"
+}
diff --git a/test/fixtures/v1/transfer.completed-legacy.json b/test/fixtures/v1/transfer.completed-legacy.json
new file mode 100644
index 0000000..948fdfc
--- /dev/null
+++ b/test/fixtures/v1/transfer.completed-legacy.json
@@ -0,0 +1,10 @@
+{
+ "id": "tx_1001",
+ "recipient": "amina@example.com",
+ "from": "USD",
+ "to": "NGN",
+ "sendAmount": 200,
+ "receiveAmount": 294620,
+ "status": "completed",
+ "createdAt": "2026-05-28T10:15:00Z"
+}
diff --git a/test/fixtures/v1/transfer.expired.json b/test/fixtures/v1/transfer.expired.json
new file mode 100644
index 0000000..98af94b
--- /dev/null
+++ b/test/fixtures/v1/transfer.expired.json
@@ -0,0 +1,14 @@
+{
+ "id": "tx_2007",
+ "recipient": "amina@example.com",
+ "from": "GBP",
+ "to": "MXN",
+ "sendAmount": "50.00",
+ "receiveAmount": "1074.70",
+ "fee": "0.35",
+ "rate": "21.645569620253",
+ "status": "expired",
+ "failureReason": null,
+ "createdAt": "2026-08-01T12:00:00Z",
+ "expiresAt": "2026-08-01T12:01:00Z"
+}
diff --git a/test/fixtures/v1/transfer.failed.json b/test/fixtures/v1/transfer.failed.json
new file mode 100644
index 0000000..be012f0
--- /dev/null
+++ b/test/fixtures/v1/transfer.failed.json
@@ -0,0 +1,13 @@
+{
+ "id": "tx_2006",
+ "recipient": "unreachable@example.com",
+ "from": "USD",
+ "to": "PHP",
+ "sendAmount": "75.00",
+ "receiveAmount": "4351.97",
+ "fee": "0.48",
+ "rate": "58.4",
+ "status": "failed",
+ "failureReason": "Destination account does not have a trustline for the asset",
+ "createdAt": "2026-08-01T11:00:00Z"
+}
diff --git a/test/fixtures/v1/transfer.forward-compatible.json b/test/fixtures/v1/transfer.forward-compatible.json
new file mode 100644
index 0000000..4a9c784
--- /dev/null
+++ b/test/fixtures/v1/transfer.forward-compatible.json
@@ -0,0 +1,15 @@
+{
+ "id": "tx_2100",
+ "recipient": "amina@example.com",
+ "from": "USD",
+ "to": "NGN",
+ "sendAmount": "200.00",
+ "receiveAmount": "294471.45",
+ "fee": "1.10",
+ "rate": "1480.5",
+ "status": "pending",
+ "createdAt": "2026-08-01T10:00:00Z",
+ "settlementNetwork": "stellar",
+ "corridorRiskScore": 3,
+ "complianceHold": false
+}
diff --git a/test/fixtures/v1/transfer.pending.json b/test/fixtures/v1/transfer.pending.json
new file mode 100644
index 0000000..5b4c67c
--- /dev/null
+++ b/test/fixtures/v1/transfer.pending.json
@@ -0,0 +1,12 @@
+{
+ "id": "tx_2004",
+ "recipient": "GBQAZ7Z3X7DEMOPUBLICKEY4REMITFLOWWALLET123456789ABCDEF",
+ "from": "USD",
+ "to": "INR",
+ "sendAmount": "120.00",
+ "receiveAmount": "9925.76",
+ "fee": "0.70",
+ "rate": "83.2",
+ "status": "pending",
+ "createdAt": "2026-08-01T10:00:20Z"
+}
diff --git a/test/fixtures/v1/transfer.quoted.json b/test/fixtures/v1/transfer.quoted.json
new file mode 100644
index 0000000..bdb0a26
--- /dev/null
+++ b/test/fixtures/v1/transfer.quoted.json
@@ -0,0 +1,13 @@
+{
+ "id": "tx_2001",
+ "recipient": "amina@example.com",
+ "from": "USD",
+ "to": "NGN",
+ "sendAmount": "200.00",
+ "receiveAmount": "294471.45",
+ "fee": "1.10",
+ "rate": "1480.5",
+ "status": "quoted",
+ "createdAt": "2026-08-01T10:00:00Z",
+ "expiresAt": "2026-08-01T10:01:00Z"
+}
diff --git a/test/fixtures/v1/transfer.settled.json b/test/fixtures/v1/transfer.settled.json
new file mode 100644
index 0000000..84e344e
--- /dev/null
+++ b/test/fixtures/v1/transfer.settled.json
@@ -0,0 +1,12 @@
+{
+ "id": "tx_2005",
+ "recipient": "amina@example.com",
+ "from": "USD",
+ "to": "NGN",
+ "sendAmount": "200.00",
+ "receiveAmount": "294471.45",
+ "fee": "1.10",
+ "rate": "1480.5",
+ "status": "settled",
+ "createdAt": "2026-08-01T10:05:00Z"
+}
diff --git a/test/fixtures/v1/transfer.validating.json b/test/fixtures/v1/transfer.validating.json
new file mode 100644
index 0000000..f56c3e9
--- /dev/null
+++ b/test/fixtures/v1/transfer.validating.json
@@ -0,0 +1,12 @@
+{
+ "id": "tx_2002",
+ "recipient": "amina@example.com",
+ "from": "USD",
+ "to": "NGN",
+ "sendAmount": "200.00",
+ "receiveAmount": "294471.45",
+ "fee": "1.10",
+ "rate": "1480.5",
+ "status": "validating",
+ "createdAt": "2026-08-01T10:00:05Z"
+}
diff --git a/test/integration/send-money-precision.test.jsx b/test/integration/send-money-precision.test.jsx
new file mode 100644
index 0000000..f5cf076
--- /dev/null
+++ b/test/integration/send-money-precision.test.jsx
@@ -0,0 +1,247 @@
+import { render, screen, waitFor, within } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import App from '../../src/App.jsx';
+import * as api from '../../src/services/api.js';
+import { formatCurrencyInput } from '../../src/utils/format.js';
+import { MONEY_PLACEHOLDER } from '../../src/utils/money.js';
+import { parseTransfer } from '../../src/services/contracts/transfer.js';
+
+// Intl separates a currency code from its amount with a non-breaking space.
+// Compare on the collapsed form so the expectations stay readable whatever
+// Testing Library's normalizer does with it.
+const money = (expected) => (content) =>
+ content.replace(/ /g, ' ') === expected;
+
+async function fillForm(user, { amount, to = 'NGN' } = {}) {
+ await user.type(screen.getByLabelText(/recipient/i), 'amina@example.com');
+ const amountField = screen.getByLabelText(/^amount$/i);
+ await user.type(amountField, amount);
+ await user.tab();
+ await user.selectOptions(screen.getByLabelText(/^to$/i), to);
+ return amountField;
+}
+
+describe('Send flow — amount parsing regressions', () => {
+ beforeEach(() => {
+ window.history.pushState({}, '', '/send');
+ localStorage.clear();
+ // The mock wallet service rejects 10% of connections at random. Pin it so
+ // the send flow is deterministic without standing up a live provider.
+ vi.spyOn(Math, 'random').mockReturnValue(0.5);
+ });
+
+ afterEach(() => {
+ vi.restoreAllMocks();
+ });
+
+ // The original failure mode: the blur handler stripped every non-digit
+ // before parsing, so the perfectly valid `