Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
90 changes: 84 additions & 6 deletions cli/src/deposit.ts
Original file line number Diff line number Diff line change
@@ -1,5 +1,22 @@
/** Account-agnostic deposit domain. POST execution requires an action-scoped captured contract. */
export type DepositPaymentMethod = "bank_standard" | "bank_instant" | "debit_card";

/** Published reset cadence only; quotas remain authenticated per source × rail × destination observations. */
export const DEPOSIT_RAIL_METADATA = {
bank_standard: {
limitReset: { timezone: "America/New_York", cadence: "business_day", localTime: "19:00" },
publishedSettlement: "up_to_5_business_days",
},
bank_instant: {
limitReset: { timezone: "America/New_York", cadence: "calendar_day", localTime: "00:00" },
publishedFee: "none",
publishedSettlement: "minutes",
},
debit_card: {
limitReset: { timezone: "America/New_York", cadence: "calendar_day", localTime: "00:00" },
publishedSettlement: "typically_30_minutes",
},
} as const;
export type DepositRequestStatus =
| "captured_exact_write_contract"
| "missing_exact_write_contract"
Expand Down Expand Up @@ -39,18 +56,46 @@ export interface CapturedDepositRequest {
amountField: string;
}

export interface RetirementContribution {
export interface IraContribution {
/** Selected through the IRA contribution flow only; never a generic deposit field. */
contributionYear: number;
contributionRoomUsd: string;
eligibilityVerified: boolean;
}
/** @deprecated Use IraContribution. Retained only for input compatibility. */
export type RetirementContribution = IraContribution;

export interface DepositLimitWindow {
period: "per_transfer" | "daily" | "rolling";
amountRemainingUsd?: string;
countRemaining?: number;
windowEndsAt?: string;
}

/** An authenticated, action-specific source × rail × destination limit observation; never a published maximum. */
export interface DepositLimitQuote {
sourceId: string;
method: DepositPaymentMethod;
destinationAccountId: string;
observedAt: string;
eligible: boolean;
fee: { known: boolean; usd?: string };
holds: string[];
windows: DepositLimitWindow[];
provenance: "authenticated_limit_read";
}

export interface DepositInput {
amountUsd: string;
destination: DepositDestination;
source: Pick<DepositSource, "id" | "method" | "eligible">;
fee: { known: boolean; usd?: string };
history: DepositHistoryRow[];
/** Required for a live-eligible quote: exact account/source/rail observation from Transfers → limits. */
limitQuote?: DepositLimitQuote;
/** Used only when destination is ira/ira_roth; binds an IRA contribution-year contract. */
iraContribution?: IraContribution;
/** @deprecated Use iraContribution. */
retirement?: RetirementContribution;
capturedRequest?: CapturedDepositRequest;
}
Expand Down Expand Up @@ -146,17 +191,50 @@ export function buildDepositQuote(input: DepositInput): DepositQuote {
gates.push(`${input.source.method} source is not eligible`);
if (!input.fee.known || asCents(input.fee.usd) !== 0)
gates.push("fee is unknown or non-zero; no fee is authorized");
const limit = input.limitQuote;
if (!limit) {
gates.push("source × rail × destination authenticated limit quote is missing");
} else {
if (
limit.sourceId !== input.source.id ||
limit.method !== input.source.method ||
limit.destinationAccountId !== input.destination.accountId ||
limit.provenance !== "authenticated_limit_read"
)
gates.push("limit quote does not bind this source × rail × destination");
if (!Number.isFinite(Date.parse(limit.observedAt)))
gates.push("limit quote timestamp is invalid");
if (!limit.eligible) gates.push("limit quote reports this deposit route as ineligible");
if (!limit.fee.known || asCents(limit.fee.usd) !== 0)
gates.push("limit quote fee is unknown or non-zero; no fee is authorized");
if (limit.holds.length) gates.push("limit quote reports an active hold");
if (!limit.windows.length) gates.push("limit quote contains no quota windows");
for (const window of limit.windows) {
if (
(asCents(window.amountRemainingUsd) ?? Number.MAX_SAFE_INTEGER) <
(amountCents ?? Number.MAX_SAFE_INTEGER)
)
gates.push(`${window.period} amount remaining is below deposit amount`);
if (
window.countRemaining !== undefined &&
(!Number.isInteger(window.countRemaining) || window.countRemaining < 1)
)
gates.push(`${window.period} transfer count remaining is exhausted`);
if (window.windowEndsAt !== undefined && !Number.isFinite(Date.parse(window.windowEndsAt)))
gates.push(`${window.period} quota reset timestamp is invalid`);
}
}
const contribution = input.iraContribution ?? input.retirement;
if (isRetirementDestination(input.destination.accountType)) {
if (!input.retirement?.eligibilityVerified)
if (!contribution?.eligibilityVerified)
gates.push("retirement contribution eligibility is not verified");
if (
!Number.isInteger(input.retirement?.contributionYear) ||
(input.retirement?.contributionYear ?? 0) < 2020
!Number.isInteger(contribution?.contributionYear) ||
(contribution?.contributionYear ?? 0) < 2020
)
gates.push("retirement contribution year is invalid");
if (
(asCents(input.retirement?.contributionRoomUsd) ?? -1) <
(amountCents ?? Number.MAX_SAFE_INTEGER)
(asCents(contribution?.contributionRoomUsd) ?? -1) < (amountCents ?? Number.MAX_SAFE_INTEGER)
)
gates.push("verified retirement contribution room is below deposit amount");
}
Expand Down
3 changes: 3 additions & 0 deletions cli/src/lib.ts
Original file line number Diff line number Diff line change
Expand Up @@ -6,11 +6,14 @@ export {
buildDepositQuote,
classifyDepositReceipt,
executeDeposit,
DEPOSIT_RAIL_METADATA,
} from "./deposit.js";
export type {
CapturedDepositRequest as GenericCapturedDepositRequest,
DepositInput,
DepositInventory,
DepositLimitQuote,
DepositLimitWindow,
DepositPlan,
DepositQuote,
DepositReceipt,
Expand Down
141 changes: 133 additions & 8 deletions cli/test/deposit.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -30,10 +30,28 @@ const request = {
body: { direction: "deposit", relationship: "placeholder" },
amountField: "amount",
};
const limitQuote = (
sourceId: string,
method: "bank_standard" | "bank_instant" | "debit_card",
destinationAccountId: string,
) => ({
sourceId,
method,
destinationAccountId,
observedAt: "2026-09-11T15:00:00.000Z",
eligible: true,
fee: { known: true, usd: "0.00" },
holds: [],
windows: [{ period: "per_transfer" as const, amountRemainingUsd: "100.00", countRemaining: 1 }],
provenance: "authenticated_limit_read" as const,
});

describe("generic deposit contracts", () => {
it("discovers every eligible owned destination and observed funding source without imposing Roth selection", () => {
const inventory = buildDepositInventory([taxable, roth, traditionalIra], [bankA, bankB, debitA]);
const inventory = buildDepositInventory(
[taxable, roth, traditionalIra],
[bankA, bankB, debitA],
);
expect(inventory.destinations).toEqual([
{ accountId: "taxable-a", accountType: "brokerage", depositEnabled: true },
{ accountId: "roth-a", accountType: "ira_roth", depositEnabled: true },
Expand All @@ -56,6 +74,7 @@ describe("generic deposit contracts", () => {
destination: { accountId: "taxable-a", accountType: "brokerage", depositEnabled: true },
source: { id: "bank-b", method: "bank_standard", eligible: true },
fee: { known: true, usd: "0.00" },
limitQuote: limitQuote("bank-b", "bank_standard", "taxable-a"),
history: [],
});
expect(quote).toMatchObject({ executable: true, amountUsd: "25.00", gates: [] });
Expand All @@ -68,17 +87,32 @@ describe("generic deposit contracts", () => {
fee: { known: true, usd: "0.00" },
history: [],
};
const taxableDestination = { accountId: taxable.id, accountType: taxable.type, depositEnabled: true };
const taxableDestination = {
accountId: taxable.id,
accountType: taxable.type,
depositEnabled: true,
};
const rothDestination = { accountId: roth.id, accountType: roth.type, depositEnabled: true };
expect(buildDepositQuote({ ...base, destination: taxableDestination }).executable).toBe(true);
expect(
buildDepositQuote({
...base,
destination: taxableDestination,
limitQuote: limitQuote("bank-a", "bank_instant", taxable.id),
}).executable,
).toBe(true);
expect(buildDepositQuote({ ...base, destination: rothDestination }).gates).toContain(
"retirement contribution eligibility is not verified",
);
expect(
buildDepositQuote({
...base,
destination: rothDestination,
retirement: { contributionYear: 2026, contributionRoomUsd: "1.00", eligibilityVerified: true },
limitQuote: limitQuote("bank-a", "bank_instant", roth.id),
retirement: {
contributionYear: 2026,
contributionRoomUsd: "1.00",
eligibilityVerified: true,
},
}).executable,
).toBe(true);
});
Expand All @@ -89,11 +123,18 @@ describe("generic deposit contracts", () => {
destination: { accountId: "ira-a", accountType: "ira", depositEnabled: true },
source: { id: "debit-a", method: "debit_card" as const, eligible: true },
fee: { known: true, usd: "0.00" },
retirement: { contributionYear: 2026, contributionRoomUsd: "1.00", eligibilityVerified: true },
limitQuote: limitQuote("debit-a", "debit_card", "ira-a"),
retirement: {
contributionYear: 2026,
contributionRoomUsd: "1.00",
eligibilityVerified: true,
},
history: [],
};
expect(buildDepositPlan(input).executable).toBe(false);
expect(buildDepositPlan(input).gates).toContain("exact deposit write contract has not been captured");
expect(buildDepositPlan(input).gates).toContain(
"exact deposit write contract has not been captured",
);
expect(buildDepositPlan({ ...input, capturedRequest: request })).toMatchObject({
executable: true,
request,
Expand All @@ -102,11 +143,95 @@ describe("generic deposit contracts", () => {
});
});

it("binds dynamic limits and fees to each source × rail × destination without aggregating unrelated sources", () => {
const base = {
amountUsd: "10.00",
destination: { accountId: "taxable-a", accountType: "brokerage", depositEnabled: true },
source: { id: "bank-a", method: "bank_standard" as const, eligible: true },
fee: { known: true, usd: "0.00" },
history: [],
};
const bankATaxable = limitQuote("bank-a", "bank_standard", "taxable-a");
const cardATaxable = {
...limitQuote("card-a", "debit_card", "taxable-a"),
fee: { known: true, usd: "0.25" },
};
const bankBRoth = {
...limitQuote("bank-b", "bank_instant", "roth-a"),
windows: [
{
period: "daily" as const,
amountRemainingUsd: "9.99",
countRemaining: 0,
windowEndsAt: "2026-09-12T04:00:00.000Z",
},
],
};
expect(buildDepositQuote({ ...base, limitQuote: bankATaxable }).executable).toBe(true);
expect(
buildDepositQuote({
...base,
source: { id: "card-a", method: "debit_card", eligible: true },
limitQuote: cardATaxable,
}).gates,
).toContain("limit quote fee is unknown or non-zero; no fee is authorized");
expect(
buildDepositQuote({
...base,
source: { id: "bank-b", method: "bank_instant", eligible: true },
destination: { accountId: "roth-a", accountType: "ira_roth", depositEnabled: true },
retirement: {
contributionYear: 2026,
contributionRoomUsd: "10.00",
eligibilityVerified: true,
},
limitQuote: bankBRoth,
}).gates,
).toEqual(
expect.arrayContaining([
"daily amount remaining is below deposit amount",
"daily transfer count remaining is exhausted",
]),
);
expect(
buildDepositQuote({
...base,
source: { id: "card-b", method: "debit_card", eligible: true },
limitQuote: bankATaxable,
}).gates,
).toContain("limit quote does not bind this source × rail × destination");
});

it("rejects missing authenticated limit reads and invalid captured non-POST contracts", () => {
const input = {
amountUsd: "1.00",
destination: { accountId: "taxable-a", accountType: "brokerage", depositEnabled: true },
source: { id: "bank-a", method: "bank_standard" as const, eligible: true },
fee: { known: true, usd: "0.00" },
history: [],
};
expect(buildDepositQuote(input).gates).toContain(
"source × rail × destination authenticated limit quote is missing",
);
expect(
buildDepositPlan({
...input,
limitQuote: limitQuote("bank-a", "bank_standard", "taxable-a"),
capturedRequest: { ...request, method: "PUT" as never },
}).gates,
).toContain("captured deposit write contract is incomplete");
});

it("keeps receipt status generic and marks transport uncertainty ambiguous", () => {
expect(classifyDepositReceipt({ status: 201, body: { id: "synthetic-receipt" } })).toMatchObject({
expect(
classifyDepositReceipt({ status: 201, body: { id: "synthetic-receipt" } }),
).toMatchObject({
submitted: true,
receiptStatus: "accepted",
});
expect(classifyDepositReceipt()).toMatchObject({ ambiguous: true, receiptStatus: "transport_ambiguous" });
expect(classifyDepositReceipt()).toMatchObject({
ambiguous: true,
receiptStatus: "transport_ambiguous",
});
});
});
Loading