@venlyfinance/react 0.1.0

package/dist/flows/staged-transfer.d.ts

@@ -0,0 +1,114 @@
+import type { Transfer, VenlyFinanceClient } from "@venlyfinance/sdk";
+import { type VenlyClients } from "../provider.js";
+type CreateFiatBody = Parameters<VenlyFinanceClient["transfers"]["createFiat"]>[1];
+type CreateCryptoBody = Parameters<VenlyFinanceClient["transfers"]["createCrypto"]>[1];
+/**
+ * The API contract requires an idempotencyKey on the create body; in this
+ * machine the key is pinned by stage(), so drafts may omit it (a provided
+ * key is honoured and pinned instead).
+ */
+type DraftBody<B extends {
+    idempotencyKey: string;
+}> = Omit<B, "idempotencyKey"> & {
+    idempotencyKey?: string;
+};
+/** What the operator is composing. Discriminated on the money rail. */
+export type TransferDraft = {
+    kind: "fiat";
+    senderAccountId: string;
+    body: DraftBody<CreateFiatBody>;
+} | {
+    kind: "crypto";
+    senderAccountId: string;
+    body: DraftBody<CreateCryptoBody>;
+};
+/**
+ * The exact request that will be sent on confirm. The idempotency key is
+ * pinned at staging time: however many times confirm() is retried (double
+ * click, flaky network, impatient operator), the API can only execute the
+ * movement once. This mirrors the settlement MCP's stage-then-confirm write
+ * gate, where the dry-run answer IS the request that later executes.
+ */
+export interface StagedRequest {
+    draft: TransferDraft;
+    idempotencyKey: string;
+    stagedAt: string;
+}
+export type StagedTransferState = {
+    phase: "draft";
+    issues: string[];
+} | {
+    phase: "staged";
+    staged: StagedRequest;
+} | {
+    phase: "submitting";
+    staged: StagedRequest;
+} | {
+    phase: "pending";
+    staged: StagedRequest;
+    transfer: Transfer;
+} | {
+    phase: "completed";
+    staged: StagedRequest;
+    transfer: Transfer;
+} | {
+    phase: "failed";
+    staged?: StagedRequest;
+    transfer?: Transfer;
+    error?: unknown;
+    reason: "submit-error" | "transfer-failed" | "poll-timeout";
+};
+/**
+ * Structural validation only: presence and sign, never business rules the
+ * API owns (limits, compliance, balance). A draft that passes here can still
+ * be rejected server-side; that surfaces as phase "failed".
+ */
+export declare function validateDraft(draft: TransferDraft): string[];
+export interface StagedTransferOptions {
+    /** Poll interval for status while the transfer is PENDING. Default 1500ms. */
+    pollIntervalMs?: number;
+    /** Give up polling after this long and report "poll-timeout". Default 120s. */
+    maxPollMs?: number;
+}
+/**
+ * Framework-agnostic core of the stage-then-confirm machine, so the whole
+ * lifecycle is testable without a DOM. The React hook below is a thin
+ * subscription over this class.
+ *
+ * draft → stage() → staged → confirm() → submitting → pending → completed
+ *                     │  ↑                                    ↘ failed
+ *                edit()  └──────────────────────────────────────┘
+ */
+export declare class StagedTransferController {
+    #private;
+    private readonly clients;
+    private readonly options;
+    constructor(clients: VenlyClients, options?: StagedTransferOptions);
+    subscribe: (listener: () => void) => (() => void);
+    getSnapshot: () => StagedTransferState;
+    /** Validate and freeze the draft; pins the idempotency key. */
+    stage(draft: TransferDraft): boolean;
+    /** Back to composing; the staged request (and its key) is discarded. */
+    edit(): void;
+    reset(): void;
+    /** Execute the staged request, then poll until the transfer is terminal. */
+    confirm(): Promise<void>;
+    dispose(): void;
+}
+/**
+ * Stage-then-confirm transfer flow.
+ *
+ * ```tsx
+ * const t = useStagedTransfer();
+ * t.stage({ kind: "fiat", senderAccountId, body });  // review screen renders t.state.staged
+ * await t.confirm();                                  // executes once, then polls to terminal
+ * ```
+ */
+export declare function useStagedTransfer(options?: StagedTransferOptions): {
+    state: StagedTransferState;
+    stage: (draft: TransferDraft) => boolean;
+    edit: () => void;
+    confirm: () => Promise<void>;
+    reset: () => void;
+};
+export {};

package/dist/flows/staged-transfer.js

@@ -0,0 +1,182 @@
+import { useEffect, useRef, useSyncExternalStore } from "react";
+import { useVenly } from "../provider.js";
+/**
+ * Structural validation only: presence and sign, never business rules the
+ * API owns (limits, compliance, balance). A draft that passes here can still
+ * be rejected server-side; that surfaces as phase "failed".
+ */
+export function validateDraft(draft) {
+    const issues = [];
+    if (!draft.senderAccountId)
+        issues.push("senderAccountId is required");
+    if (!draft.body) {
+        issues.push("body is required");
+        return issues;
+    }
+    const amount = draft.body.amount;
+    if (typeof amount === "number" && !(amount > 0)) {
+        issues.push("amount must be greater than zero");
+    }
+    if (draft.kind === "fiat" && !draft.body.currency) {
+        issues.push("currency is required for a fiat transfer");
+    }
+    if (draft.kind === "crypto") {
+        if (!draft.body.asset)
+            issues.push("asset is required for a crypto transfer");
+        if (!draft.body.chain)
+            issues.push("chain is required for a crypto transfer");
+    }
+    return issues;
+}
+const INITIAL = { phase: "draft", issues: [] };
+/**
+ * Framework-agnostic core of the stage-then-confirm machine, so the whole
+ * lifecycle is testable without a DOM. The React hook below is a thin
+ * subscription over this class.
+ *
+ * draft → stage() → staged → confirm() → submitting → pending → completed
+ *                     │  ↑                                    ↘ failed
+ *                edit()  └──────────────────────────────────────┘
+ */
+export class StagedTransferController {
+    clients;
+    options;
+    #state = INITIAL;
+    #listeners = new Set();
+    #disposed = false;
+    #pollTimer;
+    constructor(clients, options = {}) {
+        this.clients = clients;
+        this.options = options;
+    }
+    subscribe = (listener) => {
+        this.#listeners.add(listener);
+        return () => this.#listeners.delete(listener);
+    };
+    getSnapshot = () => this.#state;
+    /** Validate and freeze the draft; pins the idempotency key. */
+    stage(draft) {
+        const issues = validateDraft(draft);
+        if (issues.length > 0) {
+            this.#set({ phase: "draft", issues });
+            return false;
+        }
+        const bodyKey = draft.body.idempotencyKey;
+        this.#set({
+            phase: "staged",
+            staged: {
+                draft,
+                idempotencyKey: bodyKey ?? crypto.randomUUID(),
+                stagedAt: new Date().toISOString(),
+            },
+        });
+        return true;
+    }
+    /** Back to composing; the staged request (and its key) is discarded. */
+    edit() {
+        if (this.#state.phase === "staged")
+            this.#set(INITIAL);
+    }
+    reset() {
+        this.#clearPoll();
+        this.#set(INITIAL);
+    }
+    /** Execute the staged request, then poll until the transfer is terminal. */
+    async confirm() {
+        if (this.#state.phase !== "staged")
+            return;
+        const staged = this.#state.staged;
+        this.#set({ phase: "submitting", staged });
+        let transfer;
+        try {
+            const { draft, idempotencyKey } = staged;
+            transfer =
+                draft.kind === "fiat"
+                    ? await this.clients.finance.transfers.createFiat(draft.senderAccountId, { ...draft.body, idempotencyKey })
+                    : await this.clients.finance.transfers.createCrypto(draft.senderAccountId, { ...draft.body, idempotencyKey });
+        }
+        catch (error) {
+            this.#set({ phase: "failed", staged, error, reason: "submit-error" });
+            return;
+        }
+        if (this.#disposed)
+            return;
+        const next = this.#applyTransfer(staged, transfer);
+        if (next.phase === "pending") {
+            this.#poll(staged, transfer, Date.now());
+        }
+    }
+    dispose() {
+        this.#disposed = true;
+        this.#clearPoll();
+        this.#listeners.clear();
+    }
+    #applyTransfer(staged, transfer) {
+        const next = transfer.status === "COMPLETED"
+            ? { phase: "completed", staged, transfer }
+            : transfer.status === "FAILED"
+                ? { phase: "failed", staged, transfer, reason: "transfer-failed" }
+                : { phase: "pending", staged, transfer };
+        this.#set(next);
+        return next;
+    }
+    #poll(staged, transfer, startedAt) {
+        const interval = this.options.pollIntervalMs ?? 1_500;
+        const maxPollMs = this.options.maxPollMs ?? 120_000;
+        this.#pollTimer = setTimeout(async () => {
+            if (this.#disposed)
+                return;
+            if (Date.now() - startedAt > maxPollMs) {
+                this.#set({ phase: "failed", staged, transfer, reason: "poll-timeout" });
+                return;
+            }
+            try {
+                const fresh = await this.clients.finance.transfers.get(staged.draft.senderAccountId, transfer.id ?? "");
+                if (this.#disposed)
+                    return;
+                const next = this.#applyTransfer(staged, fresh);
+                if (next.phase === "pending")
+                    this.#poll(staged, fresh, startedAt);
+            }
+            catch {
+                // Transient read failure: keep the last known state and try again.
+                if (!this.#disposed)
+                    this.#poll(staged, transfer, startedAt);
+            }
+        }, interval);
+    }
+    #clearPoll() {
+        if (this.#pollTimer !== undefined)
+            clearTimeout(this.#pollTimer);
+        this.#pollTimer = undefined;
+    }
+    #set(state) {
+        this.#state = state;
+        for (const listener of this.#listeners)
+            listener();
+    }
+}
+/**
+ * Stage-then-confirm transfer flow.
+ *
+ * ```tsx
+ * const t = useStagedTransfer();
+ * t.stage({ kind: "fiat", senderAccountId, body });  // review screen renders t.state.staged
+ * await t.confirm();                                  // executes once, then polls to terminal
+ * ```
+ */
+export function useStagedTransfer(options) {
+    const clients = useVenly();
+    const ref = useRef(null);
+    ref.current ??= new StagedTransferController(clients, options);
+    const controller = ref.current;
+    useEffect(() => () => controller.dispose(), [controller]);
+    const state = useSyncExternalStore(controller.subscribe, controller.getSnapshot, controller.getSnapshot);
+    return {
+        state,
+        stage: (draft) => controller.stage(draft),
+        edit: () => controller.edit(),
+        confirm: () => controller.confirm(),
+        reset: () => controller.reset(),
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+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, } from "./queries.js";
+export { useCreateAccount, useCreateParty, useCreatePaymentSession, useCreateRampRequest, useCreateVirtualBankAccount, } 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";
+export { describeRampStatus, useRampLifecycle, type RampLifecycleOptions, type RampStatus, type RampStatusDescriptor, } from "./flows/ramp-lifecycle.js";
+export { proxyClientOptions, VENLY_PROXY_SECRET_SENTINEL, type ProxyClientOptions, } from "./proxy.js";
+export { FundflowClient, VenlyApiError, VenlyAuthError, VenlyFinanceClient, } from "@venlyfinance/sdk";
+export type { Account, Party, RampRequest, Transfer, VirtualBankAccount, Wallet, } from "@venlyfinance/sdk";

package/dist/index.js

@@ -0,0 +1,18 @@
+// Provider + context
+export { VenlyProvider, useVenly, useVenlyMock, } from "./provider.js";
+// Query keys + pure query factories (prefetching, loaders, tests)
+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, } from "./queries.js";
+// Write hooks
+export { useCreateAccount, useCreateParty, useCreatePaymentSession, useCreateRampRequest, useCreateVirtualBankAccount, } from "./mutations.js";
+// Flow machines: the regulated-money lifecycles
+export { StagedTransferController, useStagedTransfer, validateDraft, } from "./flows/staged-transfer.js";
+export { approvalCapabilities, interpretApprovalError, useFourEyesApproval, } from "./flows/four-eyes.js";
+export { describeRampStatus, useRampLifecycle, } from "./flows/ramp-lifecycle.js";
+// Browser-safe deployment shape
+export { proxyClientOptions, VENLY_PROXY_SECRET_SENTINEL, } from "./proxy.js";
+// Re-export the SDK surface consumers need alongside the hooks, so app code
+// can import one package. The SDK remains the canonical home.
+export { FundflowClient, VenlyApiError, VenlyAuthError, VenlyFinanceClient, } from "@venlyfinance/sdk";

package/dist/keys.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Query-key factory. Every hook and every cache invalidation goes through
+ * this object so keys can never drift apart. Keys are plain JSON values.
+ */
+export declare const venlyKeys: {
+    readonly all: readonly ["venly"];
+    readonly parties: (query?: unknown) => readonly ["venly", "parties", {} | null];
+    readonly party: (partyId: string) => readonly ["venly", "party", string];
+    readonly accounts: (query?: unknown) => readonly ["venly", "accounts", {} | null];
+    readonly account: (accountId: string) => readonly ["venly", "account", string];
+    readonly wallets: (accountId: string, query?: unknown) => readonly ["venly", "account", string, "wallets", {} | null];
+    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 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];
+    readonly referenceData: () => readonly ["venly", "reference-data"];
+    readonly companyFees: () => readonly ["venly", "company-fees"];
+    readonly feeQuote: (input: unknown) => readonly ["venly", "fee-quote", unknown];
+};

package/dist/keys.js

@@ -0,0 +1,20 @@
+/**
+ * Query-key factory. Every hook and every cache invalidation goes through
+ * this object so keys can never drift apart. Keys are plain JSON values.
+ */
+export const venlyKeys = {
+    all: ["venly"],
+    parties: (query) => ["venly", "parties", query ?? null],
+    party: (partyId) => ["venly", "party", partyId],
+    accounts: (query) => ["venly", "accounts", query ?? null],
+    account: (accountId) => ["venly", "account", accountId],
+    wallets: (accountId, query) => ["venly", "account", accountId, "wallets", query ?? null],
+    virtualBankAccounts: (accountId, query) => ["venly", "account", accountId, "virtual-bank-accounts", query ?? null],
+    transfers: (accountId, query) => ["venly", "account", accountId, "transfers", query ?? null],
+    transfer: (accountId, transferId) => ["venly", "account", accountId, "transfer", transferId],
+    rampRequests: (query) => ["venly", "ramp-requests", query ?? null],
+    rampRequest: (id) => ["venly", "ramp-request", id],
+    referenceData: () => ["venly", "reference-data"],
+    companyFees: () => ["venly", "company-fees"],
+    feeQuote: (input) => ["venly", "fee-quote", input],
+};

package/dist/mutations.d.ts

@@ -0,0 +1,123 @@
+import type { VenlyFinanceClient } from "@venlyfinance/sdk";
+type CreateVibaBody = Parameters<VenlyFinanceClient["virtualBankAccounts"]["create"]>[1];
+type CreatePaymentSessionBody = Parameters<VenlyFinanceClient["paymentSessions"]["create"]>[1];
+/** Create a party (individual or organisation), then refresh party lists. */
+export declare function useCreateParty(): import("@tanstack/react-query").UseMutationResult<{
+    id?: string;
+    externalId?: string;
+    partyType?: import("@venlyfinance/sdk").FinanceComponents["schemas"]["PartyType"];
+    status?: import("@venlyfinance/sdk").FinanceComponents["schemas"]["PartyStatus"];
+    firstName?: string;
+    lastName?: string;
+    kycStatus?: import("@venlyfinance/sdk").FinanceComponents["schemas"]["KycStatus"];
+    name?: string;
+    vatNumber?: string;
+    kybStatus?: import("@venlyfinance/sdk").FinanceComponents["schemas"]["KybStatus"];
+    address?: import("@venlyfinance/sdk").FinanceComponents["schemas"]["Address"];
+    createdAt?: string;
+    updatedAt?: string;
+    version?: number;
+}, Error, {
+    partyType: import("@venlyfinance/sdk").FinanceComponents["schemas"]["PartyType"];
+    externalId?: string;
+    firstName?: string;
+    lastName?: string;
+    name?: string;
+    vatNumber?: string;
+    address?: import("@venlyfinance/sdk").FinanceComponents["schemas"]["Address"];
+}, unknown>;
+export declare function useCreateAccount(): import("@tanstack/react-query").UseMutationResult<{
+    id?: string;
+    externalId?: string;
+    name?: string;
+    kycStatus?: import("@venlyfinance/sdk").FinanceComponents["schemas"]["KycStatus"];
+    status?: import("@venlyfinance/sdk").FinanceComponents["schemas"]["AccountStatus"];
+    createdAt?: string;
+    version?: number;
+}, Error, {
+    externalId: string;
+    name?: string;
+    chain: import("@venlyfinance/sdk").FinanceComponents["schemas"]["BlockchainNetwork"];
+    address?: string;
+    partyId?: string;
+    party?: import("@venlyfinance/sdk").FinanceComponents["schemas"]["CreatePartyRequest"];
+    cardProviderReference?: import("@venlyfinance/sdk").FinanceComponents["schemas"]["CardProviderReference"];
+}, unknown>;
+export declare function useCreateVirtualBankAccount(): import("@tanstack/react-query").UseMutationResult<{
+    id?: string;
+    accountId?: string;
+    bankAccountType?: import("@venlyfinance/sdk").FinanceComponents["schemas"]["BankAccountType"];
+    name?: string;
+    status?: import("@venlyfinance/sdk").FinanceComponents["schemas"]["VirtualBankAccountStatus"];
+    currency?: import("@venlyfinance/sdk").FinanceComponents["schemas"]["FiatCurrency"];
+    targetCryptocurrency?: import("@venlyfinance/sdk").FinanceComponents["schemas"]["Cryptocurrency"];
+    iban?: string;
+    bic?: string;
+    bankName?: string;
+    beneficiaryName?: string;
+    referenceCode?: string;
+    createdAt?: string;
+    updatedAt?: string;
+}, Error, {
+    accountId: string;
+    body: CreateVibaBody;
+}, unknown>;
+export declare function useCreatePaymentSession(): import("@tanstack/react-query").UseMutationResult<{
+    id?: string;
+    accountId?: string;
+    status?: import("@venlyfinance/sdk").FinanceComponents["schemas"]["PaymentSessionStatus"];
+    inAmount?: number;
+    inCurrency?: string;
+    outCryptocurrency?: string;
+    paymentUrl?: string;
+    externalRef?: string;
+    walletId?: string;
+    blockchainTxId?: string | null;
+    cancellable?: boolean;
+    expiresAt?: string;
+    metadata?: {
+        [key: string]: string;
+    };
+    idempotencyKey?: string;
+    createdAt?: string;
+    updatedAt?: string;
+}, Error, {
+    accountId: string;
+    body: CreatePaymentSessionBody;
+}, unknown>;
+export declare function useCreateRampRequest(): import("@tanstack/react-query").UseMutationResult<{
+    id?: string;
+    companyId?: string;
+    companyName?: string;
+    rampType?: "ON_RAMP" | "OFF_RAMP";
+    status?: "AWAITING_APPROVAL" | "AWAITING_FUNDS" | "PROCESSING" | "SUCCEEDED" | "FAILED" | "BLOCKED" | "DENIED" | "REJECTED" | "CANCELLED";
+    amount?: number;
+    netAmount?: number;
+    fiatAmount?: number;
+    fiatNetAmount?: number;
+    cryptoAmount?: number;
+    fiatFeeAmount?: number;
+    exchangeRate?: number;
+    feePercentage?: number;
+    paymentReference?: string;
+    paymentReceived?: boolean;
+    blockchainTransactionHash?: string;
+    createdAt?: string;
+    companyBankAccount?: import("@venlyfinance/sdk").FundflowComponents["schemas"]["EurSepaCompanyBankAccountDto"] | import("@venlyfinance/sdk").FundflowComponents["schemas"]["GbpChapsCompanyBankAccountDto"] | import("@venlyfinance/sdk").FundflowComponents["schemas"]["GbpFpsCompanyBankAccountDto"] | import("@venlyfinance/sdk").FundflowComponents["schemas"]["OtherCurrencySwiftCompanyBankAccountDto"] | import("@venlyfinance/sdk").FundflowComponents["schemas"]["UsAchCompanyBankAccountDto"] | import("@venlyfinance/sdk").FundflowComponents["schemas"]["UsSwiftCompanyBankAccountDto"] | import("@venlyfinance/sdk").FundflowComponents["schemas"]["UsWireCompanyBankAccountDto"];
+    companyWallet?: import("@venlyfinance/sdk").FundflowComponents["schemas"]["CompanyWalletDto"];
+    depositBankAccount?: import("@venlyfinance/sdk").FundflowComponents["schemas"]["EurSepaDepositBankAccountDto"] | import("@venlyfinance/sdk").FundflowComponents["schemas"]["GbpChapsDepositBankAccountDto"] | import("@venlyfinance/sdk").FundflowComponents["schemas"]["GbpFpsDepositBankAccountDto"] | import("@venlyfinance/sdk").FundflowComponents["schemas"]["OtherCurrencySwiftDepositBankAccountDto"] | import("@venlyfinance/sdk").FundflowComponents["schemas"]["UsAchDepositBankAccountDto"] | import("@venlyfinance/sdk").FundflowComponents["schemas"]["UsSwiftDepositBankAccountDto"] | import("@venlyfinance/sdk").FundflowComponents["schemas"]["UsWireDepositBankAccountDto"];
+    depositWallet?: import("@venlyfinance/sdk").FundflowComponents["schemas"]["DepositWalletDto"];
+    fiatCurrency?: import("@venlyfinance/sdk").FundflowComponents["schemas"]["FiatCurrencyDto"];
+    cryptoCurrency?: import("@venlyfinance/sdk").FundflowComponents["schemas"]["CryptoCurrencyDto"];
+    events?: import("@venlyfinance/sdk").FundflowComponents["schemas"]["RampRequestEventDto"][];
+    version?: number;
+    amountReceived?: number;
+}, Error, {
+    rampType: "ON_RAMP" | "OFF_RAMP";
+    amount: number;
+    companyBankAccountId?: string;
+    companyWalletId?: string;
+    fiatCurrencyId: string;
+    cryptoCurrencyId: string;
+}, unknown>;
+export {};

package/dist/mutations.js

@@ -0,0 +1,58 @@
+import { useMutation, useQueryClient } from "@tanstack/react-query";
+import { useVenly } from "./provider.js";
+import { venlyKeys } from "./keys.js";
+/** Create a party (individual or organisation), then refresh party lists. */
+export function useCreateParty() {
+    const { finance } = useVenly();
+    const queryClient = useQueryClient();
+    return useMutation({
+        mutationFn: (body) => finance.parties.create(body),
+        onSuccess: (party) => {
+            if (party.id)
+                queryClient.setQueryData(venlyKeys.party(party.id), party);
+            void queryClient.invalidateQueries({ queryKey: ["venly", "parties"] });
+        },
+    });
+}
+export function useCreateAccount() {
+    const { finance } = useVenly();
+    const queryClient = useQueryClient();
+    return useMutation({
+        mutationFn: (body) => finance.accounts.create(body),
+        onSuccess: (account) => {
+            if (account.id)
+                queryClient.setQueryData(venlyKeys.account(account.id), account);
+            void queryClient.invalidateQueries({ queryKey: ["venly", "accounts"] });
+        },
+    });
+}
+export function useCreateVirtualBankAccount() {
+    const { finance } = useVenly();
+    const queryClient = useQueryClient();
+    return useMutation({
+        mutationFn: (input) => finance.virtualBankAccounts.create(input.accountId, input.body),
+        onSuccess: (_viba, input) => {
+            void queryClient.invalidateQueries({
+                queryKey: ["venly", "account", input.accountId, "virtual-bank-accounts"],
+            });
+        },
+    });
+}
+export function useCreatePaymentSession() {
+    const { finance } = useVenly();
+    return useMutation({
+        mutationFn: (input) => finance.paymentSessions.create(input.accountId, input.body),
+    });
+}
+export function useCreateRampRequest() {
+    const { fundflow } = useVenly();
+    const queryClient = useQueryClient();
+    return useMutation({
+        mutationFn: (body) => fundflow.rampRequests.create(body),
+        onSuccess: (request) => {
+            if (request.id)
+                queryClient.setQueryData(venlyKeys.rampRequest(request.id), request);
+            void queryClient.invalidateQueries({ queryKey: ["venly", "ramp-requests"] });
+        },
+    });
+}

package/dist/provider.d.ts

@@ -0,0 +1,66 @@
+import { type ReactNode } from "react";
+import { QueryClient } from "@tanstack/react-query";
+import { FundflowClient, VenlyFinanceClient, type FundflowClientOptions, type VenlyFinanceClientOptions } from "@venlyfinance/sdk";
+/**
+ * Environments the provider accepts. "mock" constructs both clients with
+ * zero credentials and zero network (the SDK's stateful fixture store);
+ * "staging" and "production" require credentials or pre-built clients.
+ */
+export type VenlyReactEnvironment = "mock" | "staging" | "production";
+/** The pair of configured API clients every hook resolves from context. */
+export interface VenlyClients {
+    environment: VenlyReactEnvironment;
+    finance: VenlyFinanceClient;
+    fundflow: FundflowClient;
+}
+export interface VenlyProviderProps {
+    /**
+     * Default "mock": zero credentials, zero network, seeded fixtures. The
+     * same component tree flips to staging/production by changing this prop
+     * and supplying credentials server-side or a proxy.
+     */
+    environment?: VenlyReactEnvironment;
+    /**
+     * OAuth2 client-credentials. SERVER-SIDE ONLY (React Server Components,
+     * route handlers, tests). The provider throws if a secret reaches a
+     * browser bundle outside mock mode: a leaked clientSecret is full API
+     * access. For browser apps use `proxyClientOptions()` and keep the
+     * credentials behind your own backend.
+     */
+    clientId?: string;
+    clientSecret?: string;
+    /** Pre-built clients (win over environment/credentials/options). */
+    finance?: VenlyFinanceClient;
+    fundflow?: FundflowClient;
+    /** Full per-client options, e.g. from `proxyClientOptions()`. */
+    financeOptions?: VenlyFinanceClientOptions;
+    fundflowOptions?: FundflowClientOptions;
+    /**
+     * Reuse the app's QueryClient. When omitted a private one is created with
+     * retry disabled: the SDK already retries transient failures (429/5xx
+     * with backoff), and stacking a second retry layer multiplies latency.
+     */
+    queryClient?: QueryClient;
+    children?: ReactNode;
+}
+/**
+ * Context provider for every hook in this package.
+ *
+ * ```tsx
+ * <VenlyProvider environment="mock">
+ *   <App />
+ * </VenlyProvider>
+ * ```
+ */
+export declare function VenlyProvider(props: VenlyProviderProps): import("react").FunctionComponentElement<import("@tanstack/react-query").QueryClientProviderProps>;
+/** The configured clients. Throws outside a `<VenlyProvider>`. */
+export declare function useVenly(): VenlyClients;
+/**
+ * Mock controls (call log, failNext, lifecycle advancement). Defined only
+ * when the provider runs with environment "mock"; both fields are undefined
+ * otherwise, so demo/test affordances can never fire against live money.
+ */
+export declare function useVenlyMock(): {
+    finance: import("@venlyfinance/sdk").VenlyFinanceMock | undefined;
+    fundflow: import("@venlyfinance/sdk").VenlyMock | undefined;
+};