Frontend Integration Guide

npm i @prophetx/sdk-react

import { ProphetXProvider, useDeposit, useWithdraw } from '@prophetx/sdk-react';

function App() {
  return (
    <ProphetXProvider
      environment="production"
      token={sessionJwt}                     // get this from your backend, or use auth={...} (see below)
    >
      <WalletButtons />
    </ProphetXProvider>
  );
}

function WalletButtons() {
  const deposit  = useDeposit();
  const withdraw = useWithdraw();

  return (
    <>
      <button onClick={() => deposit.open({
        onSuccess: (txId, amount) => console.log('Deposited', txId, amount),
        onError:   (code, msg)    => console.error('Deposit failed', code, msg),
        onCancel:  () => console.log('User cancelled'),
      })}>
        Deposit
      </button>

      <button onClick={() => withdraw.open({
        onSuccess: (txId, amount) => console.log('Withdrew', txId, amount),
        onError:   (code, msg)    => console.error('Withdrawal failed', code, msg),
      })}>
        Withdraw
      </button>
    </>
  );
}

npm i @prophetx/sdk-js

import { createProphetX } from '@prophetx/sdk-js';

const px = createProphetX({ environment: 'production' });

document.querySelector('#deposit-btn').addEventListener('click', () => {
  px.openDeposit({
    token: sessionJwt,
    onSuccess: (txId, amount) => console.log('Deposited', txId, amount),
    onError:   (code, msg)    => console.error(code, msg),
    onCancel:  () => console.log('User cancelled'),
  });
});

// Clean up when your page tears down
window.addEventListener('beforeunload', () => px.destroy());

npm i @prophetx/sdk-react-native react-native-webview @react-native-async-storage/async-storage
cd ios && pod install      # iOS only

import { ProphetXProvider, useDeposit } from '@prophetx/sdk-react-native';

export default function App() {
  return (
    <ProphetXProvider environment="production" token={sessionJwt}>
      <Home />
    </ProphetXProvider>
  );
}

function Home() {
  const { open } = useDeposit();
  return <Button title="Deposit" onPress={() => open({
    onSuccess: (txId, amount) => console.log('Deposited', txId, amount),
    onError:   (code, msg)    => console.error('Deposit failed', code, msg),
  })} />;
}

dependencies:
  prophetx_sdk:
    git:
      url: [email protected]:betprophet1/isv-embed-fe.git
      path: packages/sdk-flutter
      ref: flutter-sdk-v0.1.0   # use the latest published tag

import 'package:flutter/material.dart';
import 'package:prophetx_sdk/prophetx_sdk.dart';

void main() {
  runApp(
    ProphetXProvider(
      environment: EnvironmentName.production,
      token: sessionJwt,
      child: const MyApp(),
    ),
  );
}

class HomeScreen extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    final px = ProphetX.of(context);
    return ElevatedButton(
      onPressed: () => px.deposit.open(OpenDepositOptions(
        onSuccess: (id, amount) => debugPrint('deposit success $id'),
        onError: (code, message) => debugPrint('deposit failed $code: $message'),
      )),
      child: const Text('Deposit'),
    );
  }
}

flow.open({
  // Lifecycle callbacks
  onReady?,
  onSuccess?,
  onError?,
  onCancel?,

  // KYC / geofence callbacks (when applicable)
  onKycSuccess?, onKycFailed?, onKycPending?,
  onGeofenceBlocked?,

  // Per-invocation theme override
  theme?,

  // Manual session refresh (not needed if you use the auth module)
  onSessionExpired?,
});

// React
const { open } = useDeposit();
open({
  onSuccess: (txId, amount) => track('deposit_success', { txId, amount }),
  onError:   (code, msg)    => track('deposit_error', { code, msg }),
  onCancel:  ()             => track('deposit_cancel'),
});

const { open } = useWithdraw();
open({
  onSuccess: (txId, amount) => console.log('Withdrew', txId, amount),
  onError:   (code, msg) => {
    if (code === 'KYC_REQUIRED') {
      // This user already exists (they have an embed token) — re-verify them,
      // don't send them through signup.
      idUpload.open();
    }
  },
});

const { open } = useOneClickSignup();
const { sessionKey, environment } = await myBackend.mintOneClickSession();
open({
  sessionKey,
  environment,
  onOneClickSuccess: (identityUuid) => myBackend.redeem(identityUuid),
  onOneClickDeclined: () => showManualSignupForm(),
  onOneClickFailed: (reason, retryable) => console.warn('1-Click failed', reason, retryable),
});

const { open: idUpload } = useIdUpload(); // or useKyc — same flow
idUpload.open({
  onKycSuccess: () => handleSuccess(),
  onKycFailed: (reason, retryable) => console.warn('Verification failed', reason, retryable),
  onKycPending: () => toast('Identity check pending review'),
});

// React
<ProphetXProvider
  environment="staging"
  auth={{
    apiBaseUrl: 'https://isv-api.staging.prophetx.dev',
    refreshBufferSeconds: 30,   // auto-refresh 30s before expiry
  }}
>
  <App />
</ProphetXProvider>

function Login() {
  const { login, logout, isAuthenticated, state } = useAuth();

  if (!isAuthenticated) {
    return (
      <button onClick={() => login({ email: '[email protected]', password: 'pw' })}>
        Sign in
      </button>
    );
  }
  return <button onClick={logout}>Sign out (expires {state.expiresAt})</button>;
}

// Vanilla JS
const px = createProphetX({
  environment: 'staging',
  auth: { apiBaseUrl: 'https://isv-api.staging.prophetx.dev' },
});

await px.auth.login({ email, password });
px.auth.onStateChange((state) => console.log('Auth →', state.status));
px.auth.logout();

// React
const { balance, loading, error, refetch } = useWallet();
return loading ? <Spinner /> : <p>${balance?.totalBalance}</p>;

// Vanilla JS
const { totalBalance, currency } = await px.wallet.getBalance();

// 1. On the provider (default for all flows)
<ProphetXProvider
  environment="production"
  token={jwt}
  theme={{
    mode: 'dark',
    primaryColor: '#4F46E5',
    backgroundColor: '#1a1a2e',
    colorOverrides:  { 'text-primary': '#fff' },
    radiusOverrides: { sm: '4px', md: '8px', lg: '16px' },
  }}
>...

// 2. Per-invocation override
px.openDeposit({ theme: { mode: 'light' } });

// Vanilla JS
px.updateTheme({ mode: 'light' });

// React — just change the prop, the provider re-sends automatically
const [theme, setTheme] = useState({ mode: 'light' });
<ProphetXProvider theme={theme} ...>...</ProphetXProvider>

type ThemePayload = {
  mode?: 'light' | 'dark';
  primaryColor?: string;
  backgroundColor?: string;
  colorOverrides?: Record<string, string>;
  spacingOverrides?: Record<string, string>;
  radiusOverrides?: Record<string, string>;
  fontSizeOverrides?: Record<string, string>;
};

// React
import { useEvents } from '@prophetx/sdk-react';

function Analytics() {
  useEvents({
    onReady:          ()     => analytics.track('embed_ready'),
    onSuccess:        (d)    => analytics.track('flow_success', d),
    onError:          (d)    => errorReporter.capture('flow_error', d),
    onCancel:         ()     => analytics.track('flow_cancel'),
    onGeofenceBlocked:(d)    => analytics.track('geofence_block', d),
    onKycSuccess:     (d)    => analytics.track('kyc_success', d),
    onKycFailed:      (d)    => analytics.track('kyc_failed', d),
    onKycPending:     ()     => analytics.track('kyc_pending'),
  });
  return null;
}

// Vanilla JS
const unsub = px.on('success', (d) => analytics.track('deposit_success', d));
px.on('error',   (d) => errorReporter.capture('sdk_error', d));
px.on('open',    (d) => analytics.track('flow_open', { flow: d.flow }));
px.on('close',   (d) => analytics.track('flow_close', { flow: d.flow }));
unsub();

deposit.open({
  onGeofenceBlocked: (stateCode, reason) => {
    // reason: 'region' | 'vpn' | 'error'
    if (reason === 'vpn') showVpnWarning();
    else showStateUnavailable(stateCode);
  },
});

<ProphetXProvider
  environment="production"
  token={jwt}
  onSessionExpired={async () => {
    const res  = await fetch('/api/auth/refresh');
    const data = await res.json();
    return data.token;  // return null to abort
  }}
>...

px.openDeposit({
  token: jwt,
  onSessionExpired: async () => (await refresh()).token,
});

<ProphetXProvider
  environment="staging"
  devtools={{
    enabled: true,
    logLevel: 'debug',           // 'none' | 'error' | 'warn' | 'info' | 'debug'
    redactPII: true,             // default true; masks tokens, emails, passwords
    onEvent: (entry) => myLogger.log(entry.category, entry.message, entry.data),
  }}
>...

// Preset (recommended)
createProphetX({ environment: 'staging' });
<ProphetXProvider environment="staging" .../>

// Custom (point at your own deploys)
createProphetX({
  environment: { embedUrl: 'https://embed.example.com', apiBaseUrl: 'https://api.example.com' },
});

px.close();    // close the active flow modal
px.destroy();  // tear the whole SDK down

<ProphetXProvider
  environment? : 'production' | 'staging' | 'sandbox' | EnvironmentConfig
  token?       : string                                // omit when using `auth`
  theme?       : ThemePayload
  auth?        : { apiBaseUrl: string, refreshBufferSeconds?: number }
  devtools?    : DevToolsConfig
  onSessionExpired? : () => Promise<string | null>
>

// Flow hooks
useDeposit():        { open(opts?), close(), isOpen }
useWithdraw():       { open(opts?), close(), isOpen }
useOneClickSignup(): { open(opts), close(), isOpen }   // opts required — needs sessionKey
useKyc() / useIdUpload(): { open(opts?), close(), isOpen }  // same flow, two names

// Module hooks
useAuth():   { state, login, logout, token, isAuthenticated }
useWallet(): { balance, loading, error, refetch }
useEvents(handlers): void

createProphetX({ environment?, auth?, devtools? }): SDKInstance

type SDKInstance = {
  openDeposit(opts):        void;
  openWithdraw(opts):       void;
  openOnboarding(opts):     void;  // opens the gated error screen — see the 1-Click Signup warning above
  openOneClickSignup(opts): void;  // opts required — needs sessionKey/environment
  openKyc(opts):            void;  // historical alias
  openIdUpload(opts):       void;  // same flow as openKyc, preferred name
  close():       void;
  destroy():     void;
  updateTheme(theme):  void;
  updateLocale(locale): void;
  on(event, handler):  () => void;
  off(event, handler): void;
  auth:   AuthManager  | null;   // null until `auth` configured
  wallet: WalletClient | null;
};

type OpenOptions = {
  token?: string;                                // not needed with auth module
  theme?: ThemePayload;
  onReady?: () => void;
  onSuccess?: (transactionId: string, amount?: number) => void;
  onError?:   (code: string, message: string) => void;
  onCancel?:  () => void;
  onGeofenceBlocked?: (stateCode: string, reason: string) => void;
  onSessionExpired?:  () => Promise<string | null>;
};

type KycOpenOptions = OpenOptions & {
  onKycSuccess?: (identityUuid: string) => void;
  onKycFailed?:  (reason: string) => void;
  onKycPending?: () => void;
};

ProphetXProvider(
  environment: EnvironmentName.production,         // or EnvironmentConfig(...)
  token: jwt,
  auth: AuthConfig(apiBaseUrl: '...'),
  theme: const EmbedTheme(mode: 'dark'),
  locale: 'en',
  child: const MyApp(),
);

final px = ProphetX.of(context);
px.deposit.open(OpenDepositOptions(onSuccess: ...));
px.withdraw.open(...);
px.onboarding.open(...);
px.kyc.open(...);

px.auth?.login(LoginCredentials(email: ..., password: ...));
px.wallet?.refetch();
px.events.stream.listen((event) { ... });   // ReadyEvent | SuccessEvent | ...