@venlyfinance/react 0.4.0 → 0.5.0

package/AGENTS.md

@@ -9,6 +9,7 @@ You are building a financial product UI on `@venlyfinance/react`. These rules ex
 3. **Never place `clientSecret` in browser code.** The provider throws if you try. For browser apps use `proxyClientOptions()` against your own backend route.
 4. **Money movement is stage-then-confirm.** Render a review step showing `state.staged` (the exact request) before calling `confirm()`. Never wire a form submit directly to execution.
 5. **Approval UIs render the rule, not the error.** Use `capability` from `useFourEyesApproval`: when `reason` is `"actor-is-creator"`, say that a second person must approve – do not show buttons that will be refused. On failure `"stale-version"`, refetch and let the operator re-decide; never auto-retry an approval.
+6. **Gate both the screen and its runtime contract, and wire both into CI.** Run `npx @venlyfinance/settlement-mcp review "src/**/*.tsx"` for the design contract and `npx @venlyfinance/settlement-mcp verify "src/**/*.{ts,tsx}"` for package/provider/hook/proxy composition. Each fails (exit 1) on any error-severity finding. A deliberate, justified exception carries `venly-allow:<rule-id>` on the offending line or the line above.
 
 ## Rendering money states
 
@@ -31,4 +32,4 @@ The UI kit's auth and team blocks therefore render against two adapter interface
 ## Demo choreography (mock mode)
 
 `useVenlyMock()` exposes the store controls. A credible end-to-end demo:
-create party → `advanceVerification(id)` → create account → virtual bank account (note its `referenceCode`) → stage + confirm a transfer → `advanceTransfer(id)` → show the ledger. Inject failures with `failNext("CONFLICT")` to show the stale-version approval path – error states are part of the product.
+create party → `advanceVerification(id)` → create account → virtual bank account (note its `referenceCode`) → **fund it: `simulations.inbound.credit(vbaId, 500)`** (a new account holds nothing, as in production; an unfunded transfer is refused with `402 insufficient-funds`) → stage + confirm a transfer → `advanceTransfer(id)` → show the ledger, and `simulations.ledger.verify()` to prove it balances. Inject failures with `failNext("CONFLICT")` to show the stale-version approval path – error states are part of the product.

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 export { VenlyProvider, useVenly, useVenlyMock, type VenlyClients, type VenlyProviderProps, type VenlyReactEnvironment, } from "./provider.js";
 export { venlyKeys } from "./keys.js";
 export { venlyQueries, type AccountsQuery, type FeeQuoteInput, type PartiesQuery, type RampRequestsQuery, type TransfersQuery, type VirtualBankAccountsQuery, type WalletsQuery, } from "./query-options.js";
-export { useAccount, useAccounts, useCompanyFees, useFeeQuote, useParties, useParty, useRampRequest, useRampRequests, useReferenceData, useTransfer, useTransfers, useVirtualBankAccounts, useWallets, useCompanyBankAccount, useCompanyBankAccounts, useCompanyWallets, useBankAccountConfig, useDepositWallets, useRampPairs, useSupportedAssets, useAccountSupportedAssets, } from "./queries.js";
+export { useAccount, useAccounts, useCompanyFees, useFeeQuote, useParties, useParty, useRampRequest, useRampRequests, useReferenceData, useTransfer, useTransfers, useTransfersForPeriod, collectTransfersForPeriod, type TransferPeriod, type TransfersForPeriodPage, useVirtualBankAccounts, useWallets, useCompanyBankAccount, useCompanyBankAccounts, useCompanyWallets, useBankAccountConfig, useDepositWallets, useRampPairs, useSupportedAssets, useAccountSupportedAssets, } from "./queries.js";
 export { useCreateAccount, useCreateParty, useCreatePaymentSession, useCreateRampRequest, useCreateVirtualBankAccount, useCreateCompanyBankAccount, useCreateCompanyWallet, useSetRampAmount, useInitiateRamp, } from "./mutations.js";
 export { StagedTransferController, useStagedTransfer, validateDraft, type StagedRequest, type StagedTransferOptions, type StagedTransferState, type TransferDraft, } from "./flows/staged-transfer.js";
 export { approvalCapabilities, interpretApprovalError, useFourEyesApproval, type ApprovalCapability, type ApprovalFailureKind, type FourEyesState, } from "./flows/four-eyes.js";

package/dist/index.js

@@ -4,7 +4,7 @@ export { VenlyProvider, useVenly, useVenlyMock, } from "./provider.js";
 export { venlyKeys } from "./keys.js";
 export { venlyQueries, } from "./query-options.js";
 // Read hooks
-export { useAccount, useAccounts, useCompanyFees, useFeeQuote, useParties, useParty, useRampRequest, useRampRequests, useReferenceData, useTransfer, useTransfers, useVirtualBankAccounts, useWallets, useCompanyBankAccount, useCompanyBankAccounts, useCompanyWallets, useBankAccountConfig, useDepositWallets, useRampPairs, useSupportedAssets, useAccountSupportedAssets, } from "./queries.js";
+export { useAccount, useAccounts, useCompanyFees, useFeeQuote, useParties, useParty, useRampRequest, useRampRequests, useReferenceData, useTransfer, useTransfers, useTransfersForPeriod, collectTransfersForPeriod, useVirtualBankAccounts, useWallets, useCompanyBankAccount, useCompanyBankAccounts, useCompanyWallets, useBankAccountConfig, useDepositWallets, useRampPairs, useSupportedAssets, useAccountSupportedAssets, } from "./queries.js";
 // Write hooks
 export { useCreateAccount, useCreateParty, useCreatePaymentSession, useCreateRampRequest, useCreateVirtualBankAccount, useCreateCompanyBankAccount, useCreateCompanyWallet, useSetRampAmount, useInitiateRamp, } from "./mutations.js";
 // Flow machines: the regulated-money lifecycles

package/dist/keys.d.ts

@@ -13,6 +13,10 @@ export declare const venlyKeys: {
     readonly accountSupportedAssets: (accountId: string) => readonly ["venly", "account", string, "supported-assets"];
     readonly virtualBankAccounts: (accountId: string, query?: unknown) => readonly ["venly", "account", string, "virtual-bank-accounts", {} | null];
     readonly transfers: (accountId: string, query?: unknown) => readonly ["venly", "account", string, "transfers", {} | null];
+    readonly transfersForPeriod: (accountId: string, period: {
+        start: string;
+        end: string;
+    }) => readonly ["venly", "account", string, "transfers-for-period", string, string];
     readonly transfer: (accountId: string, transferId: string) => readonly ["venly", "account", string, "transfer", string];
     readonly rampRequests: (query?: unknown) => readonly ["venly", "ramp-requests", {} | null];
     readonly rampRequest: (id: string) => readonly ["venly", "ramp-request", string];

package/dist/keys.js

@@ -13,6 +13,7 @@ export const venlyKeys = {
     accountSupportedAssets: (accountId) => ["venly", "account", accountId, "supported-assets"],
     virtualBankAccounts: (accountId, query) => ["venly", "account", accountId, "virtual-bank-accounts", query ?? null],
     transfers: (accountId, query) => ["venly", "account", accountId, "transfers", query ?? null],
+    transfersForPeriod: (accountId, period) => ["venly", "account", accountId, "transfers-for-period", period.start, period.end],
     transfer: (accountId, transferId) => ["venly", "account", accountId, "transfer", transferId],
     rampRequests: (query) => ["venly", "ramp-requests", query ?? null],
     rampRequest: (id) => ["venly", "ramp-request", id],

package/dist/queries.d.ts

@@ -1,7 +1,8 @@
 import { type UseQueryOptions } from "@tanstack/react-query";
+import { type Page, type Transfer as TransferRow } from "@venlyfinance/sdk";
 import { venlyQueries, type AccountsQuery, type FeeQuoteInput, type PartiesQuery, type RampRequestsQuery, type TransfersQuery, type VirtualBankAccountsQuery, type WalletsQuery, type CompanyBankAccountsQuery, type CompanyWalletsQuery, type DepositWalletsQuery } from "./query-options.js";
 type Tune<T> = Omit<UseQueryOptions<T, Error>, "queryKey" | "queryFn">;
-export declare function useParties(query?: PartiesQuery, options?: Tune<PartiesPage>): import("@tanstack/react-query").UseQueryResult<NoInfer<import("@venlyfinance/sdk").Page<{
+export declare function useParties(query?: PartiesQuery, options?: Tune<PartiesPage>): import("@tanstack/react-query").UseQueryResult<NoInfer<Page<{
     id?: string;
     externalId?: string;
     partyType?: "INDIVIDUAL" | "ORGANISATION";
@@ -35,7 +36,7 @@ export declare function useParty(partyId: string | undefined, options?: Tune<Par
     version?: number;
 }>, Error>;
 type Party = Awaited<ReturnType<ReturnType<typeof venlyQueries.party>["queryFn"]>>;
-export declare function useAccounts(query?: AccountsQuery, options?: Tune<AccountsPage>): import("@tanstack/react-query").UseQueryResult<NoInfer<import("@venlyfinance/sdk").Page<{
+export declare function useAccounts(query?: AccountsQuery, options?: Tune<AccountsPage>): import("@tanstack/react-query").UseQueryResult<NoInfer<Page<{
     id?: string;
     externalId?: string;
     name?: string;
@@ -55,7 +56,7 @@ export declare function useAccount(accountId: string | undefined, options?: Tune
     version?: number;
 }>, Error>;
 type Account = Awaited<ReturnType<ReturnType<typeof venlyQueries.account>["queryFn"]>>;
-export declare function useWallets(accountId: string | undefined, query?: WalletsQuery, options?: Tune<WalletsPage>): import("@tanstack/react-query").UseQueryResult<NoInfer<import("@venlyfinance/sdk").Page<{
+export declare function useWallets(accountId: string | undefined, query?: WalletsQuery, options?: Tune<WalletsPage>): import("@tanstack/react-query").UseQueryResult<NoInfer<Page<{
     asset?: string;
     contractAddress?: string;
     amount?: import("@venlyfinance/sdk").FinanceComponents["schemas"]["CryptoBalanceSummaryDto"];
@@ -65,7 +66,7 @@ type WalletsPage = Awaited<ReturnType<ReturnType<typeof venlyQueries.wallets>["q
  * Tenant-wide supported assets. `decimals` per asset is the render contract
  * for amounts; cached hard (the asset set changes on deploys, not minutes).
  */
-export declare function useSupportedAssets(options?: Tune<SupportedAssetsPage>): import("@tanstack/react-query").UseQueryResult<NoInfer<import("@venlyfinance/sdk").Page<{
+export declare function useSupportedAssets(options?: Tune<SupportedAssetsPage>): import("@tanstack/react-query").UseQueryResult<NoInfer<Page<{
     chain?: "AVALANCHE" | "BASE" | "ETHEREUM" | "POLYGON" | "SOLANA";
     cryptoCurrency?: string;
     decimals?: number;
@@ -76,7 +77,7 @@ type SupportedAssetsPage = Awaited<ReturnType<ReturnType<typeof venlyQueries.sup
  * Account-scoped supported assets (adds `permitStatus`). Not frozen:
  * permit status moves while an asset activates.
  */
-export declare function useAccountSupportedAssets(accountId: string | undefined, options?: Tune<AccountSupportedAssetsPage>): import("@tanstack/react-query").UseQueryResult<NoInfer<import("@venlyfinance/sdk").Page<{
+export declare function useAccountSupportedAssets(accountId: string | undefined, options?: Tune<AccountSupportedAssetsPage>): import("@tanstack/react-query").UseQueryResult<NoInfer<Page<{
     chain?: "AVALANCHE" | "BASE" | "ETHEREUM" | "POLYGON" | "SOLANA";
     cryptoCurrency?: string;
     decimals?: number;
@@ -84,7 +85,7 @@ export declare function useAccountSupportedAssets(accountId: string | undefined,
     permitStatus?: "READY" | "ACTIVATING" | "ACTION_REQUIRED" | "PENDING" | "FAILED" | "NO_WALLET";
 }>>, Error>;
 type AccountSupportedAssetsPage = Awaited<ReturnType<ReturnType<typeof venlyQueries.accountSupportedAssets>["queryFn"]>>;
-export declare function useVirtualBankAccounts(accountId: string | undefined, query?: VirtualBankAccountsQuery, options?: Tune<VibaPage>): import("@tanstack/react-query").UseQueryResult<NoInfer<import("@venlyfinance/sdk").Page<{
+export declare function useVirtualBankAccounts(accountId: string | undefined, query?: VirtualBankAccountsQuery, options?: Tune<VibaPage>): import("@tanstack/react-query").UseQueryResult<NoInfer<Page<{
     id?: string;
     accountId?: string;
     bankAccountType?: "EUR_SEPA" | "USD_ACH";
@@ -104,7 +105,7 @@ export declare function useVirtualBankAccounts(accountId: string | undefined, qu
     updatedAt?: string;
 }>>, Error>;
 type VibaPage = Awaited<ReturnType<ReturnType<typeof venlyQueries.virtualBankAccounts>["queryFn"]>>;
-export declare function useTransfers(accountId: string | undefined, query?: TransfersQuery, options?: Tune<TransfersPage>): import("@tanstack/react-query").UseQueryResult<NoInfer<import("@venlyfinance/sdk").Page<{
+export declare function useTransfers(accountId: string | undefined, query?: TransfersQuery, options?: Tune<TransfersPage>): import("@tanstack/react-query").UseQueryResult<NoInfer<Page<{
     id?: string;
     senderAccountId?: string;
     receiverAccountId?: string;
@@ -122,6 +123,27 @@ export declare function useTransfers(accountId: string | undefined, query?: Tran
     updatedAt?: string;
 }>>, Error>;
 type TransfersPage = Awaited<ReturnType<ReturnType<typeof venlyQueries.transfers>["queryFn"]>>;
+export type TransferPeriod = {
+    start: string;
+    end: string;
+};
+export type TransfersForPeriodPage = {
+    /** Rows whose `createdAt` falls in `[start, end]`. */
+    items: TransferRow[];
+    /**
+     * Every transfer on the account after paging to completion. Opening and
+     * closing walk from the current wallet total through this full ledger;
+     * a window-only set would silently drop later movements.
+     */
+    ledger: TransferRow[];
+    resultPresent: boolean;
+};
+/**
+ * Page every transfer on the account (the list contract has no date filter),
+ * then keep the window. `iteratePages` walks `hasNextPage`.
+ */
+export declare function collectTransfersForPeriod(list: (query?: TransfersQuery) => Promise<Page<Transfer>>, period: TransferPeriod, pageSize?: number): Promise<TransfersForPeriodPage>;
+export declare function useTransfersForPeriod(accountId: string | undefined, period: TransferPeriod | undefined, options?: Tune<TransfersForPeriodPage>): import("@tanstack/react-query").UseQueryResult<NoInfer<TransfersForPeriodPage>, Error>;
 export declare function useTransfer(accountId: string | undefined, transferId: string | undefined, options?: Tune<Transfer>): import("@tanstack/react-query").UseQueryResult<NoInfer<{
     id?: string;
     senderAccountId?: string;
@@ -140,7 +162,7 @@ export declare function useTransfer(accountId: string | undefined, transferId: s
     updatedAt?: string;
 }>, Error>;
 type Transfer = Awaited<ReturnType<ReturnType<typeof venlyQueries.transfer>["queryFn"]>>;
-export declare function useRampRequests(query?: RampRequestsQuery, options?: Tune<RampPage>): import("@tanstack/react-query").UseQueryResult<NoInfer<import("@venlyfinance/sdk").Page<{
+export declare function useRampRequests(query?: RampRequestsQuery, options?: Tune<RampPage>): import("@tanstack/react-query").UseQueryResult<NoInfer<Page<{
     id?: string;
     paymentReference?: string;
     rampType?: "ON_RAMP" | "OFF_RAMP";
@@ -220,7 +242,7 @@ export declare function useFeeQuote(input: FeeQuoteInput | undefined, options?:
     percentage?: number;
 }>, Error>;
 type FeeQuote = Awaited<ReturnType<ReturnType<typeof venlyQueries.feeQuote>["queryFn"]>>;
-export declare function useCompanyBankAccounts(query?: CompanyBankAccountsQuery, options?: Tune<BankAccountsPage>): import("@tanstack/react-query").UseQueryResult<NoInfer<import("@venlyfinance/sdk").Page<{
+export declare function useCompanyBankAccounts(query?: CompanyBankAccountsQuery, options?: Tune<BankAccountsPage>): import("@tanstack/react-query").UseQueryResult<NoInfer<Page<{
     id?: string;
     name?: string;
     bankName?: string;
@@ -268,7 +290,7 @@ export declare function useCompanyBankAccount(id: string | undefined, options?:
     currency?: string;
 }>, Error>;
 type BankAccountDetail = Awaited<ReturnType<ReturnType<typeof venlyQueries.companyBankAccount>["queryFn"]>>;
-export declare function useCompanyWallets(query?: CompanyWalletsQuery, options?: Tune<WalletsListPage>): import("@tanstack/react-query").UseQueryResult<NoInfer<import("@venlyfinance/sdk").Page<{
+export declare function useCompanyWallets(query?: CompanyWalletsQuery, options?: Tune<WalletsListPage>): import("@tanstack/react-query").UseQueryResult<NoInfer<Page<{
     id?: string;
     description?: string;
     address?: string;

package/dist/queries.js

@@ -1,6 +1,8 @@
 import { useQuery } from "@tanstack/react-query";
+import { iteratePages } from "@venlyfinance/sdk";
 import { useVenly } from "./provider.js";
 import { venlyQueries, } from "./query-options.js";
+import { venlyKeys } from "./keys.js";
 export function useParties(query, options) {
     const clients = useVenly();
     return useQuery({ ...venlyQueries.parties(clients, query), ...options });
@@ -73,6 +75,34 @@ export function useTransfers(accountId, query, options) {
         ...options,
     });
 }
+/**
+ * Page every transfer on the account (the list contract has no date filter),
+ * then keep the window. `iteratePages` walks `hasNextPage`.
+ */
+export async function collectTransfersForPeriod(list, period, pageSize = 20) {
+    const ledger = [];
+    for await (const item of iteratePages((params) => list({ page: params.page, size: params.size }), {
+        size: pageSize,
+    })) {
+        ledger.push(item);
+    }
+    const items = ledger.filter((transfer) => {
+        const at = transfer.createdAt;
+        return Boolean(at && at >= period.start && at <= period.end);
+    });
+    return { items, ledger, resultPresent: true };
+}
+export function useTransfersForPeriod(accountId, period, options) {
+    const clients = useVenly();
+    const start = period?.start ?? "";
+    const end = period?.end ?? "";
+    return useQuery({
+        queryKey: venlyKeys.transfersForPeriod(accountId ?? "", { start, end }),
+        queryFn: () => collectTransfersForPeriod((query) => clients.finance.transfers.list(accountId ?? "", query), { start, end }),
+        enabled: Boolean(accountId && start && end) && (options?.enabled ?? true),
+        ...options,
+    });
+}
 export function useTransfer(accountId, transferId, options) {
     const clients = useVenly();
     return useQuery({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@venlyfinance/react",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Headless React layer for the Venly Finance and Fundflow APIs: provider, TanStack Query hooks, and flow state machines for regulated money movement. Runs with zero credentials in mock mode.",
   "type": "module",
   "main": "./dist/index.js",