JSPM

  • Created
  • Published
  • Downloads 2947
  • Score
    100M100P100Q114342F
  • License MIT

React hooks for Bluvo SDK - Framework-agnostic state machine for crypto withdrawals

Package Exports

    This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@bluvo/react) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

    Readme

    @bluvo/react

    React hooks for the Bluvo SDK - providing a framework-agnostic, event-driven state machine for cryptocurrency withdrawal flows.

    Installation

    npm install @bluvo/react @bluvo/sdk-ts
    # or
    pnpm add @bluvo/react @bluvo/sdk-ts
    # or
    yarn add @bluvo/react @bluvo/sdk-ts

    Quick Start

    import React from 'react';
    import { useBluvoFlow } from '@bluvo/react';
    
    function WithdrawalComponent() {
        const flow = useBluvoFlow({
            orgId: "bluvo-org-id",
            projectId: "bluvo-project-id", // <- deprecated soon to be removed
    
            fetchWithdrawableBalanceFn: fetchWithdrawableBalances,
            requestQuotationFn: requestQuotation,
            executeWithdrawalFn: executeWithdrawal,
    
            onWalletConnectedFn: (walletId, exchange) => {
                // call server action store this walletId for the currently-logged in user
            }
        });
    
      const handleStart = () => {
        flow.startWithdrawalFlow({
          exchange: 'coinbase',
          walletId: 'wallet-123',
          asset: 'BTC',
          amount: '0.001',
          destinationAddress: 'bc1q...'
        });
      };
    
      if (flow.requires2FA) {
        return (
          <div>
            <input 
              placeholder="Enter 2FA code"
              onKeyPress={(e) => {
                if (e.key === 'Enter') {
                  flow.submit2FA(e.target.value);
                }
              }}
            />
          </div>
        );
      }
    
      return (
        <div>
          <button onClick={handleStart}>Start Withdrawal</button>
          <p>State: {flow.state?.type}</p>
        </div>
      );
    }

    Available Hooks

    useBluvoFlow(options)

    The main hook that manages the entire withdrawal flow state machine.

    Options:

    • orgId - Your Bluvo organization ID
    • projectId - Your Bluvo project ID
    • fetchWithdrawableBalanceFn - Function to fetch wallet balances
    • requestQuotationFn - Function to request withdrawal quotes
    • executeWithdrawalFn - Function to execute withdrawals
    • maxRetryAttempts? - Maximum retry attempts (default: 3)
    • topicToken? - WebSocket topic token for real-time updates
    • cacheName? - Cache name for WebSocket subscriptions
    • mkUUIDFn? - Custom UUID generator function

    Returns:

    {
      // State
      state: FlowState | null,
      error: Error | null,
      context: FlowContext,
      
      // Actions  
      startWithdrawalFlow: (options) => Promise<void>,
      executeWithdrawal: (quoteId) => Promise<void>,
      submit2FA: (code) => Promise<void>,
      submitSMS: (code) => Promise<void>,
      retryWithdrawal: () => Promise<void>,
      cancel: () => void,
      
      // State Helpers
      isOAuthPending: boolean,
      isWalletReady: boolean,
      isQuoteReady: boolean,
      requires2FA: boolean,
      requiresSMS: boolean,
      requiresKYC: boolean,
      isWithdrawalComplete: boolean,
      canRetry: boolean,
      
      // Data
      walletBalances: Array<{asset: string, balance: string}>,
      quote: Quote | null,
      withdrawal: Withdrawal | null
    }

    useFlowMachine(machine)

    Lower-level hook for direct state machine interaction.

    useWithdrawMachine(machine)

    Hook for managing the withdrawal sub-state machine.

    Security

    This library follows security best practices:

    • No API keys in browser: Uses callback functions that call your secure server endpoints
    • Server-side operations: All sensitive operations happen on your server
    • Type safety: Full TypeScript support with proper error handling

    State Flow

    idle → oauth:waiting → wallet:loading → quote:ready → withdraw:processing → completed
      ↓         ↓               ↓             ↓              ↓
    cancel   cancel        error states    2FA/SMS/KYC    success/retry

    Framework Integration

    Works seamlessly with:

    • Next.js - Use with Server Actions
    • Remix - Use with action functions
    • SvelteKit - Use with form actions
    • Any React app - Use with your API layer

    Examples

    See the examples directory for complete implementations with different frameworks.

    License

    MIT © Bluvo Inc.