@venlyfinance/react 0.1.0

package/AGENTS.md

@@ -0,0 +1,23 @@
+# Composition rules for coding agents
+
+You are building a financial product UI on `@venlyfinance/react`. These rules exist because the failure modes of money UIs are specific; follow them over generic dashboard instincts.
+
+## Non-negotiable
+
+1. **Never hand-roll API calls, auth, retries, or transfer state.** Every read is a hook (`useAccounts`, `useTransfers`, `useRampRequests`, …); every regulated lifecycle is a flow machine (`useStagedTransfer`, `useFourEyesApproval`, `useRampLifecycle`). If you are writing `fetch` or a `useEffect` polling loop, stop – the hook exists.
+2. **Wrap the tree once** in `<VenlyProvider environment="mock">`. Mock mode needs zero credentials and zero network; it is the correct default for any demo, test, or first build. Going live is a constructor change, not a rewrite.
+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.
+
+## Rendering money states
+
+- Use `descriptor` from `useRampLifecycle` for status pills and timelines: `intent` gives the semantic colour, but always pair colour with a glyph or label – state is never carried by colour alone.
+- A waiting state must answer: must I act, who is it waiting on, what still works. `descriptor.waitingOn` and `descriptor.explanation` carry this; render them instead of a bare "Pending".
+- Amounts: tabular figures, currency code after the amount, and never render a debit in red as the only signal. Empty numeric cells are an em dash, not 0.
+- Terminal failure states show the reason from the record; the status field is the explanation field.
+
+## 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.

package/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+## 0.1.0
+
+Initial release.
+
+- `<VenlyProvider>` for mock / staging / production, with a browser guard that refuses to construct credentialed clients in a bundle.
+- Read hooks for parties, accounts, wallets, virtual bank accounts, transfers, ramp requests, reference data, and fee quotes; write hooks for the create operations; `venlyKeys` / `venlyQueries` factories underneath.
+- Flow machines: `useStagedTransfer` (stage-then-confirm with the idempotency key pinned at staging), `useFourEyesApproval` (optimistic-locking version carried through, 409 → `"stale-version"`), `useRampLifecycle` (status descriptors answering must-I-act / waiting-on / what-still-works).
+- `proxyClientOptions()` for the browser-safe production shape; its placeholder credential is the exported `VENLY_PROXY_SECRET_SENTINEL`, which the browser guard recognises as not-a-secret.
+- The browser guard covers every path a secret can take into the provider: the top-level prop and both per-client options objects.
+- 30 node:test cases against the SDK's mock transport; zero network.

package/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright (c) 2026 Venly NV
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OF THE SOFTWARE.

package/README.md

@@ -0,0 +1,129 @@
+# @venlyfinance/react
+
+[![ci](https://github.com/Venly/venly-settlement-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/Venly/venly-settlement-sdk/actions/workflows/ci.yml)
+
+Headless React layer for the [Venly Finance and Fundflow APIs](https://github.com/Venly/venly-settlement-sdk). Provider, TanStack Query hooks, and flow state machines for the lifecycles that make money movement different from CRUD: stage-then-confirm execution, four-eyes approval, and status models where "pending" has four different meanings.
+
+No components, no CSS. This package owns data and state; your UI (or the one your coding agent assembles) owns the pixels. The full behaviour is covered by a node:test suite that runs with zero network.
+
+## Try it in 0 minutes (mock mode)
+
+```bash
+npm install @venlyfinance/react @tanstack/react-query
+```
+
+```tsx
+import { VenlyProvider, useAccounts } from "@venlyfinance/react";
+
+function Accounts() {
+  const { data } = useAccounts();
+  return <ul>{data?.items.map((a) => <li key={a.id}>{a.name ?? a.id}</li>)}</ul>;
+}
+
+export default function App() {
+  return (
+    <VenlyProvider environment="mock">
+      <Accounts />
+    </VenlyProvider>
+  );
+}
+```
+
+Mock mode needs zero credentials and makes zero network calls: every hook answers from the SDK's stateful, spec-validated fixture store. Create a party, watch KYC advance, stage a transfer, approve a ramp request – the whole product works on your laptop before you have an API key.
+
+## What's in the box
+
+| Export | What it does |
+|---|---|
+| `<VenlyProvider>` | Constructs the Finance + Fundflow clients for `mock`, `staging`, or `production`; brings its own QueryClient if the app has none |
+| `useParties` `useAccounts` `useWallets` `useVirtualBankAccounts` `useTransfers` `useRampRequests` `useReferenceData` `useFeeQuote` … | Read hooks, one per API resource, cache keys managed for you |
+| `useCreateParty` `useCreateAccount` `useCreateVirtualBankAccount` `useCreatePaymentSession` `useCreateRampRequest` | Write hooks with cache invalidation wired |
+| `useStagedTransfer` | Stage-then-confirm machine: validate → freeze the exact request with a pinned idempotency key → execute once → poll to terminal |
+| `useFourEyesApproval` | Approve/reject/cancel with the optimistic-locking `version` carried through; 409 surfaces as `"stale-version"` (refetch and re-decide, never auto-retry) |
+| `useRampLifecycle` | One ramp request, polled until terminal, with a status descriptor answering: must I act, who is it waiting on, what still works |
+| `venlyKeys` / `venlyQueries` | Query-key factory and pure `{queryKey, queryFn}` factories for prefetching, route loaders, and tests |
+| `useVenlyMock` | The mock controls (call log, `failNext`, `advanceVerification`, `advanceTransfer`) – defined only in mock mode |
+| `proxyClientOptions` | Browser-safe production wiring (below) |
+
+## The flow machines
+
+The hooks above the line are conveniences. These are the point:
+
+```tsx
+const t = useStagedTransfer();
+
+// 1. Stage: validates and freezes the request. The idempotency key is pinned
+//    HERE, so a double-clicked confirm can only ever execute once.
+t.stage({ kind: "fiat", senderAccountId, body: { currency: "EUR", amount: 250 } });
+
+// 2. Your review screen renders t.state.staged – the exact request that will run.
+// 3. Confirm: executes, then polls the transfer to COMPLETED or FAILED.
+await t.confirm();
+```
+
+```tsx
+const approval = useFourEyesApproval(request, currentUserId);
+
+approval.capability;        // { canApprove, canReject, canCancel, reason? }
+                            // creators see canApprove: false – render the rule, not an error
+await approval.approve();   // carries { version }; a 409 → failure "stale-version"
+```
+
+```tsx
+const { descriptor } = useRampLifecycle(id);
+descriptor.phase;        // "action-required" | "waiting" | "in-flight" | "terminal"
+descriptor.waitingOn;    // "approver" | "counterparty-funds" | "venly" | null
+descriptor.explanation;  // one sentence a support ticket would otherwise ask
+```
+
+## Going live: never put credentials in the browser
+
+The Venly APIs use OAuth2 client-credentials. A `clientSecret` in a browser bundle is full API access for anyone who opens devtools, so the provider **throws** if it sees one in a browser outside mock mode.
+
+Two supported production shapes:
+
+**Server-rendered surfaces** (RSC, route handlers): build the clients server-side with real credentials and pass them in via the `finance` / `fundflow` props.
+
+**Browser apps**: the browser talks to your backend; your backend holds the credentials.
+
+```tsx
+// client – no secrets anywhere in the bundle
+const proxy = proxyClientOptions("/api/venly");
+<VenlyProvider environment="production"
+  financeOptions={proxy.finance} fundflowOptions={proxy.fundflow} />
+```
+
+```ts
+// server – e.g. a Next.js catch-all route handler at /api/venly/finance/[...path]
+// Authenticate YOUR user first; then forward with the SDK's credentials.
+import { VenlyFinanceClient } from "@venlyfinance/sdk";
+const venly = new VenlyFinanceClient({
+  clientId: process.env.VENLY_CLIENT_ID!,
+  clientSecret: process.env.VENLY_CLIENT_SECRET!,
+  environment: "production",
+});
+export async function GET(req: Request, { params }: { params: { path: string[] } }) {
+  const result = await venly.request("GET", "/" + params.path.join("/"));
+  return Response.json(result);
+}
+```
+
+The proxy inherits your app's session security, not Venly's – enforce your own authentication and per-user authorization in the handler.
+
+## Design rules this package follows
+
+- **Types derive from the OpenAPI-generated SDK types.** No hand-written API mirrors; a spec regeneration breaks this build instead of drifting silently.
+- **TanStack retry is off by default.** The SDK already retries transient failures (429/5xx with backoff and `Retry-After`); a second retry layer multiplies latency and hides real errors.
+- **Approvals never auto-retry.** A version conflict means the world changed; the operator re-decides against the new state.
+- **Mock affordances cannot fire in production.** `useVenlyMock()` returns `undefined` handles outside mock mode.
+
+## Development
+
+```bash
+npm install
+npm run typecheck && npm run typecheck:test
+npm test          # node:test, zero network
+npm run build
+```
+
+MIT. Part of the [venly-settlement-sdk](https://github.com/Venly/venly-settlement-sdk) monorepo alongside `@venlyfinance/sdk` and `@venlyfinance/settlement-mcp`.

package/dist/flows/four-eyes.d.ts

@@ -0,0 +1,71 @@
+import { type RampRequest } from "@venlyfinance/sdk";
+/**
+ * Client-side read of what the four-eyes rule allows right now. The API is
+ * the enforcer (creator ≠ approver, optimistic locking); this function only
+ * decides what to RENDER: an approve button that will certainly be refused
+ * is worse than an explanation of who can act.
+ */
+export interface ApprovalCapability {
+    canApprove: boolean;
+    canReject: boolean;
+    canCancel: boolean;
+    /** Why approval is unavailable, when it is. */
+    reason?: "not-awaiting-approval" | "actor-is-creator";
+}
+/**
+ * Structural input: `createdBy` is carried by ramp-request LIST items but
+ * not by the detail DTO, so it is optional here and creator detection simply
+ * degrades (the API still enforces the rule) when it is absent.
+ */
+export interface ApprovalSubject {
+    status?: RampRequest["status"];
+    createdBy?: string;
+}
+export declare function approvalCapabilities(request: ApprovalSubject | undefined, actorId?: string): ApprovalCapability;
+/**
+ * Typed interpretation of an approval failure, so UI renders the correct
+ * next action instead of a generic error toast.
+ *
+ * - "stale-version": someone else acted first (HTTP 409, optimistic lock).
+ *   Correct UI: refresh the request, re-render capabilities, let the
+ *   operator re-decide against the NEW state. Never auto-retry an approval.
+ * - "forbidden": the API refused the actor (includes the server-enforced
+ *   creator≠approver rule). Correct UI: show who can act.
+ */
+export type ApprovalFailureKind = "stale-version" | "forbidden" | "not-found" | "validation" | "unknown";
+export declare function interpretApprovalError(error: unknown): ApprovalFailureKind;
+export type FourEyesState = {
+    phase: "idle";
+} | {
+    phase: "submitting";
+    action: "approve" | "reject" | "cancel";
+} | {
+    phase: "applied";
+    action: "approve" | "reject" | "cancel";
+    request: RampRequest;
+} | {
+    phase: "failed";
+    action: "approve" | "reject" | "cancel";
+    failure: ApprovalFailureKind;
+    error: unknown;
+};
+/**
+ * Four-eyes decision flow for one ramp request. Carries the optimistic-
+ * locking `version` through every action; a 409 comes back as
+ * "stale-version" so the surface can refetch-and-re-decide.
+ *
+ * ```tsx
+ * const approval = useFourEyesApproval(request, currentUserEmail);
+ * if (approval.capability.canApprove) <Button onClick={approval.approve} />
+ * ```
+ */
+export declare function useFourEyesApproval(request: (RampRequest & {
+    createdBy?: string;
+}) | undefined, actorId?: string): {
+    state: FourEyesState;
+    capability: ApprovalCapability;
+    approve: () => Promise<void>;
+    reject: () => Promise<void>;
+    cancel: () => Promise<void>;
+    reset: () => void;
+};

package/dist/flows/four-eyes.js

@@ -0,0 +1,91 @@
+import { useState } from "react";
+import { useQueryClient } from "@tanstack/react-query";
+import { VenlyApiError } from "@venlyfinance/sdk";
+import { useVenly } from "../provider.js";
+import { venlyKeys } from "../keys.js";
+export function approvalCapabilities(request, actorId) {
+    if (!request || request.status !== "AWAITING_APPROVAL") {
+        return {
+            canApprove: false,
+            canReject: false,
+            canCancel: request?.status === "AWAITING_FUNDS",
+            reason: "not-awaiting-approval",
+        };
+    }
+    if (actorId && request.createdBy && actorId === request.createdBy) {
+        // Four-eyes: the creator can cancel their own request but never approve
+        // or reject it. Rendering the buttons anyway teaches operators that
+        // errors are normal; hiding them teaches the control.
+        return { canApprove: false, canReject: false, canCancel: true, reason: "actor-is-creator" };
+    }
+    return { canApprove: true, canReject: true, canCancel: true };
+}
+export function interpretApprovalError(error) {
+    if (error instanceof VenlyApiError) {
+        if (error.status === 409)
+            return "stale-version";
+        if (error.status === 403)
+            return "forbidden";
+        if (error.status === 404)
+            return "not-found";
+        if (error.status === 400)
+            return "validation";
+    }
+    return "unknown";
+}
+/**
+ * Four-eyes decision flow for one ramp request. Carries the optimistic-
+ * locking `version` through every action; a 409 comes back as
+ * "stale-version" so the surface can refetch-and-re-decide.
+ *
+ * ```tsx
+ * const approval = useFourEyesApproval(request, currentUserEmail);
+ * if (approval.capability.canApprove) <Button onClick={approval.approve} />
+ * ```
+ */
+export function useFourEyesApproval(request, actorId) {
+    const { fundflow } = useVenly();
+    const queryClient = useQueryClient();
+    const [state, setState] = useState({ phase: "idle" });
+    const act = async (action) => {
+        if (!request?.id)
+            return;
+        if (typeof request.version !== "number") {
+            setState({
+                phase: "failed",
+                action,
+                failure: "stale-version",
+                error: new Error("Ramp request carries no version; refetch it before acting so optimistic locking can protect the decision."),
+            });
+            return;
+        }
+        setState({ phase: "submitting", action });
+        try {
+            const body = { version: request.version };
+            const updated = action === "approve"
+                ? await fundflow.rampRequests.approve(request.id, body)
+                : action === "reject"
+                    ? await fundflow.rampRequests.reject(request.id, body)
+                    : await fundflow.rampRequests.cancel(request.id, body);
+            if (updated.id)
+                queryClient.setQueryData(venlyKeys.rampRequest(updated.id), updated);
+            void queryClient.invalidateQueries({ queryKey: ["venly", "ramp-requests"] });
+            setState({ phase: "applied", action, request: updated });
+        }
+        catch (error) {
+            setState({ phase: "failed", action, failure: interpretApprovalError(error), error });
+            // A stale version means the cached request lies; make every reader refetch.
+            if (interpretApprovalError(error) === "stale-version" && request.id) {
+                void queryClient.invalidateQueries({ queryKey: venlyKeys.rampRequest(request.id) });
+            }
+        }
+    };
+    return {
+        state,
+        capability: approvalCapabilities(request, actorId),
+        approve: () => act("approve"),
+        reject: () => act("reject"),
+        cancel: () => act("cancel"),
+        reset: () => setState({ phase: "idle" }),
+    };
+}

package/dist/flows/ramp-lifecycle.d.ts

@@ -0,0 +1,96 @@
+import type { RampRequest } from "@venlyfinance/sdk";
+export type RampStatus = NonNullable<RampRequest["status"]>;
+/**
+ * A waiting state must answer four questions or it is an anxiety generator:
+ * how long, on which channel, must I act, and what still works. This
+ * descriptor encodes the answers per status so every surface renders the
+ * same truth. The status field is the explanation field.
+ */
+export interface RampStatusDescriptor {
+    status: RampStatus | "UNKNOWN";
+    /** Coarse phase for layout decisions (queue grouping, timeline register). */
+    phase: "action-required" | "waiting" | "in-flight" | "terminal";
+    /** Who the request is waiting on; null when nobody (terminal states). */
+    waitingOn: "approver" | "counterparty-funds" | "venly" | null;
+    /** Terminal outcome, only when phase is "terminal". */
+    outcome?: "succeeded" | "failed" | "declined" | "cancelled";
+    /** Semantic intent for status pills. Rendered with a glyph AND a colour —
+     * state is never carried by colour alone. */
+    intent: "positive" | "negative" | "pending" | "neutral";
+    canApprove: boolean;
+    canCancel: boolean;
+    canEditAmount: boolean;
+    isTerminal: boolean;
+    /** Short human label, sentence case. */
+    label: string;
+    /** One sentence: what is happening and whether the reader must act. */
+    explanation: string;
+}
+export declare function describeRampStatus(status: RampStatus | undefined): RampStatusDescriptor;
+export interface RampLifecycleOptions {
+    /** Poll interval while the request is non-terminal. Default 4000ms. */
+    pollIntervalMs?: number;
+}
+/**
+ * One ramp request, polled until terminal, with its status descriptor.
+ * Polling stops by itself the moment the status is terminal.
+ */
+export declare function useRampLifecycle(id: string | undefined, options?: RampLifecycleOptions): {
+    request: 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;
+    }> | undefined;
+    descriptor: RampStatusDescriptor;
+    query: 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>;
+};

package/dist/flows/ramp-lifecycle.js

@@ -0,0 +1,148 @@
+import { useQuery } from "@tanstack/react-query";
+import { useVenly } from "../provider.js";
+import { venlyQueries } from "../query-options.js";
+const DESCRIPTORS = {
+    AWAITING_APPROVAL: {
+        phase: "action-required",
+        waitingOn: "approver",
+        intent: "pending",
+        canApprove: true,
+        canCancel: true,
+        canEditAmount: true,
+        isTerminal: false,
+        label: "Awaiting approval",
+        explanation: "A second person must approve before anything moves; the creator cannot approve their own request.",
+    },
+    AWAITING_FUNDS: {
+        phase: "waiting",
+        waitingOn: "counterparty-funds",
+        intent: "pending",
+        canApprove: false,
+        canCancel: true,
+        canEditAmount: false,
+        isTerminal: false,
+        label: "Awaiting funds",
+        explanation: "Approved and waiting for the incoming payment to arrive; nothing is blocked on you, and the request can still be cancelled.",
+    },
+    PROCESSING: {
+        phase: "in-flight",
+        waitingOn: "venly",
+        intent: "pending",
+        canApprove: false,
+        canCancel: false,
+        canEditAmount: false,
+        isTerminal: false,
+        label: "Processing",
+        explanation: "Funds are moving; no action is available until this settles.",
+    },
+    SUCCEEDED: {
+        phase: "terminal",
+        waitingOn: null,
+        outcome: "succeeded",
+        intent: "positive",
+        canApprove: false,
+        canCancel: false,
+        canEditAmount: false,
+        isTerminal: true,
+        label: "Succeeded",
+        explanation: "Settled; the transaction detail carries the final amounts and references.",
+    },
+    FAILED: {
+        phase: "terminal",
+        waitingOn: null,
+        outcome: "failed",
+        intent: "negative",
+        canApprove: false,
+        canCancel: false,
+        canEditAmount: false,
+        isTerminal: true,
+        label: "Failed",
+        explanation: "The movement failed; the request record carries the reason.",
+    },
+    BLOCKED: {
+        phase: "waiting",
+        waitingOn: "venly",
+        intent: "pending",
+        canApprove: false,
+        canCancel: false,
+        canEditAmount: false,
+        isTerminal: false,
+        label: "Blocked",
+        explanation: "Held for review on the Venly side; no action is available to you while the hold stands.",
+    },
+    DENIED: {
+        phase: "terminal",
+        waitingOn: null,
+        outcome: "declined",
+        intent: "negative",
+        canApprove: false,
+        canCancel: false,
+        canEditAmount: false,
+        isTerminal: true,
+        label: "Denied",
+        explanation: "Declined during review; create a new request if circumstances change.",
+    },
+    REJECTED: {
+        phase: "terminal",
+        waitingOn: null,
+        outcome: "declined",
+        intent: "negative",
+        canApprove: false,
+        canCancel: false,
+        canEditAmount: false,
+        isTerminal: true,
+        label: "Rejected",
+        explanation: "Rejected at the approval step; the reviewer's decision is final for this request.",
+    },
+    CANCELLED: {
+        phase: "terminal",
+        waitingOn: null,
+        outcome: "cancelled",
+        intent: "neutral",
+        canApprove: false,
+        canCancel: false,
+        canEditAmount: false,
+        isTerminal: true,
+        label: "Cancelled",
+        explanation: "Withdrawn before completion; no funds moved.",
+    },
+};
+export function describeRampStatus(status) {
+    if (!status || !(status in DESCRIPTORS)) {
+        return {
+            status: "UNKNOWN",
+            phase: "waiting",
+            waitingOn: null,
+            intent: "neutral",
+            canApprove: false,
+            canCancel: false,
+            canEditAmount: false,
+            isTerminal: false,
+            label: "Unknown status",
+            explanation: "The request carries a status this version does not recognise; refetch or upgrade.",
+        };
+    }
+    return { status, ...DESCRIPTORS[status] };
+}
+/**
+ * One ramp request, polled until terminal, with its status descriptor.
+ * Polling stops by itself the moment the status is terminal.
+ */
+export function useRampLifecycle(id, options) {
+    const clients = useVenly();
+    const query = useQuery({
+        ...venlyQueries.rampRequest(clients, id ?? ""),
+        enabled: Boolean(id),
+        refetchInterval: (q) => {
+            const status = q.state.data?.status;
+            if (status && describeRampStatus(status).isTerminal)
+                return false;
+            return options?.pollIntervalMs ?? 4_000;
+        },
+    });
+    return {
+        request: query.data,
+        descriptor: describeRampStatus(query.data?.status),
+        query,
+    };
+}