@venlyfinance/react 0.1.0

package/dist/provider.js

@@ -0,0 +1,98 @@
+import { createContext, createElement, useContext, useState, } from "react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { FundflowClient, VenlyFinanceClient, } from "@venlyfinance/sdk";
+import { VENLY_PROXY_SECRET_SENTINEL } from "./proxy.js";
+const VenlyContext = createContext(null);
+/**
+ * A secret is dangerous when it would actually be used: mock-mode options
+ * ignore credentials by construction, and the proxy sentinel is a
+ * placeholder the backend never honours. Everything else is a real secret.
+ */
+function armedSecret(options) {
+    if (!options || options.environment === "mock")
+        return undefined;
+    const secret = options.clientSecret;
+    return secret && secret !== VENLY_PROXY_SECRET_SENTINEL ? secret : undefined;
+}
+function buildClients(props) {
+    const environment = props.environment ?? "mock";
+    // Guard every path a secret can take into this component: the top-level
+    // prop AND the per-client options objects (the options path would
+    // otherwise short-circuit past a top-level-only check).
+    const secretInBrowser = typeof window !== "undefined" &&
+        Boolean((environment !== "mock" && props.clientSecret) ||
+            armedSecret(props.financeOptions) ||
+            armedSecret(props.fundflowOptions));
+    if (secretInBrowser) {
+        throw new Error("[@venlyfinance/react] Refusing to construct a credentialed client in the browser: " +
+            "a bundled clientSecret is full API access for anyone who opens devtools. " +
+            "Keep credentials behind your backend and pass proxyClientOptions(), " +
+            "or build the clients in server code and pass them via the `finance`/`fundflow` props.");
+    }
+    const finance = props.finance ??
+        new VenlyFinanceClient(props.financeOptions ??
+            (environment === "mock"
+                ? { environment: "mock" }
+                : {
+                    environment,
+                    clientId: requireCredential(props.clientId, "clientId"),
+                    clientSecret: requireCredential(props.clientSecret, "clientSecret"),
+                }));
+    const fundflow = props.fundflow ??
+        new FundflowClient(props.fundflowOptions ??
+            (environment === "mock"
+                ? { environment: "mock" }
+                : {
+                    environment,
+                    clientId: requireCredential(props.clientId, "clientId"),
+                    clientSecret: requireCredential(props.clientSecret, "clientSecret"),
+                }));
+    return { environment, finance, fundflow };
+}
+function requireCredential(value, name) {
+    if (!value) {
+        throw new Error(`[@venlyfinance/react] environment is not "mock" but no ${name} was provided. ` +
+            "Pass credentials (server-side only), proxyClientOptions(), or pre-built clients.");
+    }
+    return value;
+}
+/**
+ * Context provider for every hook in this package.
+ *
+ * ```tsx
+ * <VenlyProvider environment="mock">
+ *   <App />
+ * </VenlyProvider>
+ * ```
+ */
+export function VenlyProvider(props) {
+    // Clients and the fallback QueryClient are constructed exactly once per
+    // provider instance; changing construction props requires a remount (key=).
+    const [clients] = useState(() => buildClients(props));
+    const [queryClient] = useState(() => props.queryClient ??
+        new QueryClient({
+            defaultOptions: {
+                queries: { retry: false, staleTime: 5_000, refetchOnWindowFocus: false },
+                mutations: { retry: false },
+            },
+        }));
+    return createElement(QueryClientProvider, { client: queryClient }, createElement(VenlyContext.Provider, { value: clients }, props.children));
+}
+/** The configured clients. Throws outside a `<VenlyProvider>`. */
+export function useVenly() {
+    const clients = useContext(VenlyContext);
+    if (!clients) {
+        throw new Error("[@venlyfinance/react] useVenly() called outside <VenlyProvider>. " +
+            "Wrap your tree in <VenlyProvider environment=\"mock\"> to get started.");
+    }
+    return clients;
+}
+/**
+ * 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 function useVenlyMock() {
+    const { finance, fundflow } = useVenly();
+    return { finance: finance.mock, fundflow: fundflow.mock };
+}

package/dist/proxy.d.ts

@@ -0,0 +1,39 @@
+import type { FundflowClientOptions, VenlyFinanceClientOptions } from "@venlyfinance/sdk";
+/**
+ * Client options for the browser-safe deployment shape: the browser talks to
+ * YOUR backend, and your backend holds the credentials and forwards to Venly
+ * with the real OAuth token. No secret ever enters the bundle.
+ *
+ * The SDK always runs an OAuth token flow before calling out, so this wraps
+ * `fetch` to answer the token request locally with a synthetic token (your
+ * proxy ignores the Authorization header and applies its own). Every API
+ * call then goes to `proxyBaseUrl` unchanged.
+ *
+ * ```tsx
+ * const proxy = proxyClientOptions("/api/venly");
+ * <VenlyProvider environment="production"
+ *   financeOptions={proxy.finance} fundflowOptions={proxy.fundflow} />
+ * ```
+ *
+ * Server side, the matching route handler uses the SDK with real credentials
+ * (see README "Going live" for a Next.js example) and MUST enforce its own
+ * authentication: the proxy inherits your app's session, not Venly's.
+ */
+export interface ProxyClientOptions {
+    finance: VenlyFinanceClientOptions;
+    fundflow: FundflowClientOptions;
+}
+/**
+ * The placeholder credential used by proxy options. It is not a secret –
+ * the proxy backend ignores the Authorization header entirely – and the
+ * provider's browser guard recognises it as safe. Never assign a real
+ * secret this value.
+ */
+export declare const VENLY_PROXY_SECRET_SENTINEL = "venly-proxy";
+export declare function proxyClientOptions(proxyBaseUrl: string, options?: {
+    fetch?: typeof fetch;
+    /** Path under proxyBaseUrl that forwards to the Finance API. Default "/finance". */
+    financePath?: string;
+    /** Path under proxyBaseUrl that forwards to the Fundflow API. Default "/fundflow". */
+    fundflowPath?: string;
+}): ProxyClientOptions;

package/dist/proxy.js

@@ -0,0 +1,42 @@
+/**
+ * The placeholder credential used by proxy options. It is not a secret –
+ * the proxy backend ignores the Authorization header entirely – and the
+ * provider's browser guard recognises it as safe. Never assign a real
+ * secret this value.
+ */
+export const VENLY_PROXY_SECRET_SENTINEL = "venly-proxy";
+const SYNTHETIC_TOKEN_PATH = "/__venly-proxy-token";
+export function proxyClientOptions(proxyBaseUrl, options) {
+    const base = proxyBaseUrl.replace(/\/$/, "");
+    const tokenUrl = `${base}${SYNTHETIC_TOKEN_PATH}`;
+    const realFetch = options?.fetch ?? fetch;
+    const proxyFetch = async (input, init) => {
+        const url = typeof input === "string" ? input : input instanceof URL ? input.href : input.url;
+        if (url === tokenUrl) {
+            return Response.json({
+                access_token: "venly-proxy",
+                token_type: "Bearer",
+                expires_in: 3600,
+            });
+        }
+        return realFetch(input, init);
+    };
+    return {
+        finance: {
+            environment: "production",
+            clientId: "venly-proxy",
+            clientSecret: VENLY_PROXY_SECRET_SENTINEL,
+            baseUrl: `${base}${options?.financePath ?? "/finance"}`,
+            tokenUrl,
+            fetch: proxyFetch,
+        },
+        fundflow: {
+            environment: "production",
+            clientId: "venly-proxy",
+            clientSecret: VENLY_PROXY_SECRET_SENTINEL,
+            baseUrl: `${base}${options?.fundflowPath ?? "/fundflow"}`,
+            tokenUrl,
+            fetch: proxyFetch,
+        },
+    };
+}

package/dist/queries.d.ts

@@ -0,0 +1,200 @@
+import { type UseQueryOptions } from "@tanstack/react-query";
+import { venlyQueries, type AccountsQuery, type FeeQuoteInput, type PartiesQuery, type RampRequestsQuery, type TransfersQuery, type VirtualBankAccountsQuery, type WalletsQuery } 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<{
+    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>;
+type PartiesPage = Awaited<ReturnType<ReturnType<typeof venlyQueries.parties>["queryFn"]>>;
+export declare function useParty(partyId: string | undefined, options?: Tune<Party>): import("@tanstack/react-query").UseQueryResult<NoInfer<{
+    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>;
+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<{
+    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>;
+type AccountsPage = Awaited<ReturnType<ReturnType<typeof venlyQueries.accounts>["queryFn"]>>;
+export declare function useAccount(accountId: string | undefined, options?: Tune<Account>): import("@tanstack/react-query").UseQueryResult<NoInfer<{
+    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>;
+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<{
+    id?: string;
+    chain?: import("@venlyfinance/sdk").FinanceComponents["schemas"]["BlockchainNetwork"];
+    type?: import("@venlyfinance/sdk").FinanceComponents["schemas"]["WalletType"];
+    address?: string;
+    balances?: import("@venlyfinance/sdk").FinanceComponents["schemas"]["TokenBalance"][];
+    amlStatus?: import("@venlyfinance/sdk").FinanceComponents["schemas"]["AmlStatus"];
+}>>, Error>;
+type WalletsPage = Awaited<ReturnType<ReturnType<typeof venlyQueries.wallets>["queryFn"]>>;
+export declare function useVirtualBankAccounts(accountId: string | undefined, query?: VirtualBankAccountsQuery, options?: Tune<VibaPage>): import("@tanstack/react-query").UseQueryResult<NoInfer<import("@venlyfinance/sdk").Page<{
+    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>;
+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<{
+    id?: string;
+    senderAccountId?: string;
+    receiverAccountId?: string;
+    chain?: import("@venlyfinance/sdk").FinanceComponents["schemas"]["BlockchainNetwork"];
+    asset?: string;
+    amount?: number;
+    fiatOrigin?: import("@venlyfinance/sdk").FinanceComponents["schemas"]["FiatOrigin"];
+    description?: string;
+    merchantReference?: string;
+    idempotencyKey?: string;
+    status?: import("@venlyfinance/sdk").FinanceComponents["schemas"]["TransferStatus"];
+    transactionHash?: string;
+    errorMessage?: string;
+    createdAt?: string;
+    updatedAt?: string;
+}>>, Error>;
+type TransfersPage = Awaited<ReturnType<ReturnType<typeof venlyQueries.transfers>["queryFn"]>>;
+export declare function useTransfer(accountId: string | undefined, transferId: string | undefined, options?: Tune<Transfer>): import("@tanstack/react-query").UseQueryResult<NoInfer<{
+    id?: string;
+    senderAccountId?: string;
+    receiverAccountId?: string;
+    chain?: import("@venlyfinance/sdk").FinanceComponents["schemas"]["BlockchainNetwork"];
+    asset?: string;
+    amount?: number;
+    fiatOrigin?: import("@venlyfinance/sdk").FinanceComponents["schemas"]["FiatOrigin"];
+    description?: string;
+    merchantReference?: string;
+    idempotencyKey?: string;
+    status?: import("@venlyfinance/sdk").FinanceComponents["schemas"]["TransferStatus"];
+    transactionHash?: string;
+    errorMessage?: string;
+    createdAt?: string;
+    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<{
+    id?: string;
+    paymentReference?: string;
+    rampType?: "ON_RAMP" | "OFF_RAMP";
+    status?: "AWAITING_APPROVAL" | "AWAITING_FUNDS" | "PROCESSING" | "SUCCEEDED" | "FAILED" | "BLOCKED" | "DENIED" | "REJECTED" | "CANCELLED";
+    fiatAmount?: number;
+    fiatCurrency?: string;
+    cryptoAmount?: number;
+    cryptoCurrency?: string;
+    createdAt?: string;
+    createdBy?: string;
+}>>, Error>;
+type RampPage = Awaited<ReturnType<ReturnType<typeof venlyQueries.rampRequests>["queryFn"]>>;
+export declare function useRampRequest(id: string | undefined, options?: Tune<Ramp>): import("@tanstack/react-query").UseQueryResult<NoInfer<{
+    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>;
+type Ramp = Awaited<ReturnType<ReturnType<typeof venlyQueries.rampRequest>["queryFn"]>>;
+export declare function useReferenceData(options?: Tune<ReferenceData>): import("@tanstack/react-query").UseQueryResult<NoInfer<{
+    fiatCurrencies: {
+        id?: string;
+        currency?: string;
+        label?: string;
+        enabled?: boolean;
+        version?: number;
+    }[];
+    cryptoCurrencies: {
+        id?: string;
+        currency?: string;
+        chain?: "ETHEREUM" | "POLYGON" | "BASE" | "ARBITRUM" | "SUI";
+        label?: string;
+        enabled?: boolean;
+        version?: number;
+        coingeckoId?: string;
+    }[];
+    chains: {
+        supportedChains?: ("ETHEREUM" | "POLYGON" | "BASE" | "ARBITRUM" | "SUI")[];
+    }[];
+}>, Error>;
+type ReferenceData = Awaited<ReturnType<ReturnType<typeof venlyQueries.referenceData>["queryFn"]>>;
+export declare function useCompanyFees(options?: Tune<CompanyFees>): import("@tanstack/react-query").UseQueryResult<NoInfer<{
+    id?: string;
+    companyId?: string;
+    name?: string;
+    type?: "ON_RAMP" | "OFF_RAMP";
+    minVolume?: number;
+    maxVolume?: number;
+    percentage?: number;
+    version?: number;
+}[]>, Error>;
+type CompanyFees = Awaited<ReturnType<ReturnType<typeof venlyQueries.companyFees>["queryFn"]>>;
+export declare function useFeeQuote(input: FeeQuoteInput | undefined, options?: Tune<FeeQuote>): import("@tanstack/react-query").UseQueryResult<NoInfer<{
+    amount?: number;
+    percentage?: number;
+}>, Error>;
+type FeeQuote = Awaited<ReturnType<ReturnType<typeof venlyQueries.feeQuote>["queryFn"]>>;
+export {};

package/dist/queries.js

@@ -0,0 +1,91 @@
+import { useQuery } from "@tanstack/react-query";
+import { useVenly } from "./provider.js";
+import { venlyQueries, } from "./query-options.js";
+export function useParties(query, options) {
+    const clients = useVenly();
+    return useQuery({ ...venlyQueries.parties(clients, query), ...options });
+}
+export function useParty(partyId, options) {
+    const clients = useVenly();
+    return useQuery({
+        ...venlyQueries.party(clients, partyId ?? ""),
+        enabled: Boolean(partyId) && (options?.enabled ?? true),
+        ...options,
+    });
+}
+export function useAccounts(query, options) {
+    const clients = useVenly();
+    return useQuery({ ...venlyQueries.accounts(clients, query), ...options });
+}
+export function useAccount(accountId, options) {
+    const clients = useVenly();
+    return useQuery({
+        ...venlyQueries.account(clients, accountId ?? ""),
+        enabled: Boolean(accountId) && (options?.enabled ?? true),
+        ...options,
+    });
+}
+export function useWallets(accountId, query, options) {
+    const clients = useVenly();
+    return useQuery({
+        ...venlyQueries.wallets(clients, accountId ?? "", query),
+        enabled: Boolean(accountId) && (options?.enabled ?? true),
+        ...options,
+    });
+}
+export function useVirtualBankAccounts(accountId, query, options) {
+    const clients = useVenly();
+    return useQuery({
+        ...venlyQueries.virtualBankAccounts(clients, accountId ?? "", query),
+        enabled: Boolean(accountId) && (options?.enabled ?? true),
+        ...options,
+    });
+}
+export function useTransfers(accountId, query, options) {
+    const clients = useVenly();
+    return useQuery({
+        ...venlyQueries.transfers(clients, accountId ?? "", query),
+        enabled: Boolean(accountId) && (options?.enabled ?? true),
+        ...options,
+    });
+}
+export function useTransfer(accountId, transferId, options) {
+    const clients = useVenly();
+    return useQuery({
+        ...venlyQueries.transfer(clients, accountId ?? "", transferId ?? ""),
+        enabled: Boolean(accountId && transferId) && (options?.enabled ?? true),
+        ...options,
+    });
+}
+export function useRampRequests(query, options) {
+    const clients = useVenly();
+    return useQuery({ ...venlyQueries.rampRequests(clients, query), ...options });
+}
+export function useRampRequest(id, options) {
+    const clients = useVenly();
+    return useQuery({
+        ...venlyQueries.rampRequest(clients, id ?? ""),
+        enabled: Boolean(id) && (options?.enabled ?? true),
+        ...options,
+    });
+}
+export function useReferenceData(options) {
+    const clients = useVenly();
+    return useQuery({
+        ...venlyQueries.referenceData(clients),
+        staleTime: Infinity, // chains and currencies change on deploys, not minutes
+        ...options,
+    });
+}
+export function useCompanyFees(options) {
+    const clients = useVenly();
+    return useQuery({ ...venlyQueries.companyFees(clients), ...options });
+}
+export function useFeeQuote(input, options) {
+    const clients = useVenly();
+    return useQuery({
+        ...venlyQueries.feeQuote(clients, input),
+        enabled: Boolean(input) && (options?.enabled ?? true),
+        ...options,
+    });
+}