Bluvo Widget for Svelte

A Svelte wrapper for the Bluvo widget that allows seamless integration with Svelte applications.

Installation

npm install @bluvo/widget-svelte
# or
yarn add @bluvo/widget-svelte
# or
pnpm add @bluvo/widget-svelte

Usage

Basic Usage

<script>
  import { BluvoWidget } from '@bluvo/widget-svelte';

  // Configuration options
  const widgetProps = {
    auth: {
      projectId: 'your-project-id',
      orgId: 'your-org-id',
    },
    // Optional: customize the widget
    width: 400,
    mode: 'connect', // or 'transact'
    // ... other options
  };
</script>

<BluvoWidget {...widgetProps} class="my-custom-class" />

SvelteKit Usage with Dynamic Import

For SvelteKit applications, the recommended approach is to use dynamic imports to prevent SSR issues:

<script lang="ts">
    import type { BluvoWidgetProps } from '@bluvo/widget-svelte';
    import { onMount } from 'svelte';
    let BluvoWidget: typeof import('@bluvo/widget-svelte').BluvoWidget;

    // @ts-ignore
    import { browser } from '$app/environment';

    const widgetProps: BluvoWidgetProps = {
        // Authentication
        auth: {
            orgId: 'bluvo-org-your-org-id',
            projectId: 'your-project-id',
        },
        
        // Widget configuration
        debug: true,
        storage: 'localStorage',
        showBranding: true,
        showTOS: true,
        termsOfServiceLink: 'https://bluvo.co/terms',
        privacyPolicyLink: 'https://bluvo.co/privacy',
        width: 400,
        
        // Operation mode
        mode: 'transact',
        
        // Exchanges to display
        exchanges: [
            'binance',
            'coinbase',
            'kraken',
            'kucoin',
            'bybit',
            // ...more exchanges
        ],
        
        // Connect mode settings
        connect: {
            showSearch: false,
            showSuccessDetails: true,
            ipList: [],
            useCustomIpList: false,
            exchangeList: {
                logoSize: 40,
            },
            onSuccess: (walletId: string) => {
                console.log('✅ [Connect] Wallet connected:', walletId);
            },
            onComplete: (walletId: string) => {
                console.log('✅ [Connect] User completed linking:', walletId);
            },
        },
        
        // Transaction mode settings
        transaction: {
            showSuccessDetails: true,
            ipList: [],
            useCustomIpList: false,
            display: {
                address: 'input',
                amount: 'label',
                tag: 'none',
            },
            prefill: {
                address: {
                    LTC: 'ltc1qxyz1234567890abcdefg1234567890abcdefg',
                    BTC: 'bc1qxyz1234567890abcdefg1234567890abcdefg',
                    ETH: '0x1234567890abcdef1234567890abcdef12345678',
                },
                amount: {
                    LTC: 0.01,
                    BTC: 0.001,
                    ETH: 0.01,
                },
            },
            onSuccess: (txId: string) => {
                console.log('✅ [Transact] Transaction successful:', txId);
            },
            onComplete: (txId: string) => {
                console.log('✅ [Transact] User completed transaction:', txId);
            },
        },
    };

    onMount(async () => {
        if (browser) {
            const module = await import('@bluvo/widget-svelte');
            BluvoWidget = module.BluvoWidget;
        }
    });
</script>

<main>
    <h1>Bluvo Svelte Widget Example</h1>
    <div class="widget-container">
        {#if BluvoWidget}
            <svelte:component this={BluvoWidget} {...widgetProps} class="custom-widget" />
        {:else}
            <p>Loading widget...</p>
        {/if}
    </div>
</main>

<style>
    main {
        font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
        max-width: 800px;
        margin: 0 auto;
        padding: 20px;
    }

    h1 {
        color: #333;
        text-align: center;
    }

    .widget-container {
        display: flex;
        justify-content: center;
        margin-top: 30px;
    }

    .custom-widget {
        box-shadow: 0 4px 12px rgba(0,0,0,0.1);
    }
</style>

Configuration Options

The Bluvo widget accepts the following configuration options:

Required Properties

| Option | Type | Description | |------------------|--------|-------------------------------------| | auth | Object | Required authentication credentials | | auth.projectId | String | Your Bluvo project ID | | auth.orgId | String | Your Bluvo organization ID |

Widget-Level Configuration

| Option | Type | Description | |------------------------|----------------|--------------------------------------------------------------------| | width | Number|String | Widget width (default: 360px) | | mode | String | Widget mode: 'connect' or 'transact' | | debug | Boolean | Enable debug logging (default: false) | | storage | String | Token storage strategy: 'localStorage', 'sessionStorage' or 'none' | | showBranding | Boolean | Show Bluvo branding in footer (default: true) | | showTOS | Boolean | Show Terms of Service links in footer (default: true) | | termsOfServiceLink | String | URL for Terms of Service | | privacyPolicyLink | String | URL for Privacy Policy | | exchanges | String[] | List of exchanges to display | | theme | Object | Theming options | | theme.dark | Boolean | Use dark mode (default: true) | | theme.accentColor | String | Primary accent color | | theme.secondaryColor | String | Secondary accent color |

Connect Mode Configuration

| Option | Type | Description | |---------------------------------|----------|-----------------------------------------------------------| | connect.showSearch | Boolean | Show search filter for exchanges (default: false) | | connect.showSuccessDetails | Boolean | Show wallet details on connection success (default: true) | | connect.exchangeList.logoSize | Number | Size of exchange logos in pixels (default: 40) | | connect.ipList | String[] | List of IP addresses to whitelist | | connect.useCustomIpList | Boolean | Use custom IP list (default: false) | | connect.onSuccess | Function | Called when a wallet is connected | | connect.onComplete | Function | Called when user clicks "Done" |

Transaction Mode Configuration

| Option | Type | Description | |----------------------------------|----------|------------------------------------------------------| | transaction.defaultCoin | String | Default selected coin | | transaction.coins | String[] | List of coins available for withdrawal | | transaction.showSuccessDetails | Boolean | Show transaction details on success (default: false) | | transaction.ipList | String[] | List of IP addresses to whitelist | | transaction.useCustomIpList | Boolean | Use custom IP list (default: false) | | transaction.display.address | String | Address field display mode: 'input', 'label', 'none' | | transaction.display.tag | String | Tag field display mode: 'input', 'label', 'none' | | transaction.display.amount | String | Amount field display mode: 'input', 'label', 'none' | | transaction.prefill.address | Object | Prefilled destination addresses by coin | | transaction.prefill.tag | Object | Prefilled destination tags by coin | | transaction.prefill.amount | Object | Prefilled amounts by coin | | transaction.onSuccess | Function | Called when a transaction is successful | | transaction.onComplete | Function | Called when user clicks "Done" |

Svelte-Specific Properties

| Option | Type | Description | |---------------------|----------|---------------------------------------------| | class | String | Custom CSS class name for the container div | | style | String | Custom CSS styles for the container div | | onMountCallback | Function | Callback when component is mounted | | onDestroyCallback | Function | Callback when component is destroyed |

Working with the Token Storage

The widget provides a helper function to manage tokens outside the widget:

<script>
  import { createBluvoWidgetStore } from '@bluvo/widget-svelte';
  
  // Create a store that uses localStorage (default)
  const widgetStore = createBluvoWidgetStore();
  
  // Check if user is connected to Binance
  const isConnectedToBinance = widgetStore.hasTokens('binance');
  
  // Clear tokens for a specific exchange
  function disconnect(exchangeId) {
    widgetStore.clearTokens(exchangeId);
  }
  
  // Clear all tokens
  function disconnectAll() {
    widgetStore.clearAllTokens();
  }
</script>

{#if isConnectedToBinance}
  <button on:click={() => disconnect('binance')}>
    Disconnect from Binance
  </button>
{/if}

TypeScript Support

The package includes full TypeScript definitions for all configuration options:

import type { 
  BluvoWidgetProps, 
  BluvoWidgetConfig,
  BluvoTheme, 
  BluvoConnectOptions, 
  BluvoTransactionOptions 
} from '@bluvo/widget-svelte';

// Define typed widget props
const widgetProps: BluvoWidgetProps = {
  auth: {
    projectId: 'your-project-id',
    orgId: 'your-org-id',
  },
  // All properties are properly typed
  mode: 'connect', // TypeScript will ensure this is 'connect' or 'transact'
  // ...
};

See the full documentation for more details on configuration options.

License

MIT