@supanovaapp/sdk 0.2.11 → 0.2.13

package/dist/hooks/useAPI.d.ts

@@ -0,0 +1,142 @@
+import { UserResponseDto, UserBalanceResponseDto, DialogWithMessagesResponseDto, DialogListResponseDto, OffsetPaginatedDto, MessageResponseDto, PaginationParams, NetworkAddressAndPriceDto, TokenInfoWithPriceChangeDto, TokenInfo, TokenPriceHistoryParams, TokenPriceHistoryResponse, AccountTokensBalancesResponse, AlchemyNetwork, SupaPointsBalanceResponseDto, DailyLoginResponseDto, SupaPointsHistoryParams, TransactionQueryParams, PaymasterRequestDto, PaymasterResponseDto } from '../core/types';
+/**
+ * Return type for useAPI hook
+ * Provides organized access to all backend API methods
+ */
+export interface UseAPIReturn {
+    /** User management and profile methods */
+    user: {
+        /** Fetches current authenticated user profile */
+        getCurrent: () => Promise<UserResponseDto>;
+        /** Fetches all users (admin only) */
+        getAll: () => Promise<UserResponseDto[]>;
+        /** Fetches user by Privy ID */
+        getByPrivyId: (privyUserId: string) => Promise<UserResponseDto>;
+        /** Fetches user's smart wallet token balances */
+        getBalance: (force?: boolean) => Promise<UserBalanceResponseDto>;
+    };
+    /** AI dialog management methods */
+    dialogs: {
+        /** Creates a new AI dialog with initial message */
+        create: (text: string) => Promise<DialogWithMessagesResponseDto>;
+        /** Fetches all user dialogs with pagination */
+        findAll: (params?: PaginationParams) => Promise<OffsetPaginatedDto<DialogListResponseDto>>;
+        /** Fetches a specific dialog by ID */
+        findOne: (id: number) => Promise<DialogListResponseDto>;
+        /** Deletes a dialog and all its messages */
+        delete: (id: number) => Promise<void>;
+    };
+    /** AI message methods within dialogs */
+    messages: {
+        /** Creates a new message in a dialog */
+        create: (dialogId: number, text: string) => Promise<MessageResponseDto>;
+        /** Fetches all messages in a dialog with pagination */
+        findAll: (dialogId: number, params?: PaginationParams) => Promise<OffsetPaginatedDto<MessageResponseDto>>;
+        /** Fetches a specific message by ID */
+        findOne: (id: number) => Promise<MessageResponseDto>;
+    };
+    /** On-chain data and token price methods */
+    onchain: {
+        /** Fetches token prices by contract addresses */
+        getPricesByAddresses: (addresses: Array<{
+            network: AlchemyNetwork;
+            contractAddress: string;
+        }>) => Promise<NetworkAddressAndPriceDto[]>;
+        /** Fetches token prices by symbols (BTC, ETH, etc.) */
+        getTokenPrices: (symbols: string[]) => Promise<Record<string, number>>;
+        /** Fetches historical price data for a token */
+        getPriceHistory: (params: TokenPriceHistoryParams) => Promise<TokenPriceHistoryResponse>;
+        /** Fetches 24-hour price changes for tokens */
+        get24hrPriceChanges: (tokens: Array<{
+            network: AlchemyNetwork;
+            contractAddress: string;
+        }>) => Promise<TokenInfoWithPriceChangeDto[]>;
+        /** Fetches detailed token information */
+        getTokenInfo: (network: string, addresses: string | string[]) => Promise<Record<string, TokenInfo>>;
+        /** Fetches token balances for an account */
+        getAccountBalances: (network: string, account: string, force?: boolean) => Promise<AccountTokensBalancesResponse>;
+    };
+    /** Transaction history methods */
+    transactions: {
+        /** Fetches user transaction history */
+        get: (params?: TransactionQueryParams) => Promise<any>;
+        /** Forces reload of transaction history from blockchain */
+        forceLoad: (params?: TransactionQueryParams) => Promise<any>;
+    };
+    /** SupaPoints reward system methods */
+    supaPoints: {
+        /** Fetches current SupaPoints balance */
+        getBalance: () => Promise<SupaPointsBalanceResponseDto>;
+        /** Fetches SupaPoints transaction history */
+        getHistory: (params?: SupaPointsHistoryParams) => Promise<OffsetPaginatedDto<any>>;
+        /** Processes daily login bonus */
+        dailyLogin: () => Promise<DailyLoginResponseDto>;
+    };
+    /** Paymaster sponsorship methods */
+    paymaster: {
+        /** Checks if transaction qualifies for gas sponsorship */
+        checkSponsorship: (request: PaymasterRequestDto) => Promise<PaymasterResponseDto>;
+    };
+    /** Privy wallet methods */
+    privy: {
+        /** Fetches Privy embedded wallet balance */
+        getBalance: () => Promise<any>;
+    };
+}
+/**
+ * Hook for accessing Supa Backend API
+ * Provides organized, type-safe access to all backend endpoints
+ * All methods automatically include authentication token from Privy
+ *
+ * @returns Organized API methods grouped by functionality
+ *
+ * @example
+ * Basic usage
+ * ```tsx
+ * function UserBalance() {
+ *   const api = useAPI();
+ *   const [balance, setBalance] = useState(null);
+ *
+ *   useEffect(() => {
+ *     api.user.getBalance().then(setBalance);
+ *   }, []);
+ *
+ *   return <div>Balance: ${balance?.totalUsdBalance}</div>;
+ * }
+ * ```
+ *
+ * @example
+ * Creating an AI dialog
+ * ```tsx
+ * function CreateDialog() {
+ *   const api = useAPI();
+ *
+ *   const handleCreate = async () => {
+ *     const dialog = await api.dialogs.create('Hello AI!');
+ *     console.log('Dialog created:', dialog.id);
+ *     console.log('AI response:', dialog.messages[1].message);
+ *   };
+ *
+ *   return <button onClick={handleCreate}>Start Chat</button>;
+ * }
+ * ```
+ *
+ * @example
+ * Fetching crypto prices
+ * ```tsx
+ * function TokenPrices() {
+ *   const api = useAPI();
+ *
+ *   useEffect(() => {
+ *     api.onchain.getTokenPrices(['BTC', 'ETH', 'SOL'])
+ *       .then(prices => {
+ *         console.log('BTC:', prices.BTC);
+ *         console.log('ETH:', prices.ETH);
+ *       });
+ *   }, []);
+ *
+ *   return <div>Check console for prices</div>;
+ * }
+ * ```
+ */
+export declare const useAPI: () => UseAPIReturn;

package/dist/hooks/useAuth.d.ts

@@ -0,0 +1,45 @@
+import { User as PrivyUser } from '@privy-io/react-auth';
+/**
+ * Return type for useAuth hook
+ */
+export interface UseAuthReturn {
+    /** Opens Privy login modal */
+    login: () => void;
+    /** Logs out the current user */
+    logout: () => Promise<void>;
+    /** Whether user is authenticated */
+    authenticated: boolean;
+    /** Whether authentication is in progress */
+    loading: boolean;
+    /** Privy user object containing linked accounts and profile data */
+    user: PrivyUser | null;
+    /** Gets Privy JWT access token for authenticated API calls */
+    getAccessToken: () => Promise<string | null>;
+    /** Whether SDK is ready (not loading) */
+    ready: boolean;
+}
+/**
+ * Hook for managing user authentication via Privy
+ * Automatically configures API client with access token when user authenticates
+ *
+ * @returns Authentication methods and user state
+ *
+ * @example
+ * ```tsx
+ * function LoginButton() {
+ *   const { login, logout, authenticated, user } = useAuth();
+ *
+ *   if (!authenticated) {
+ *     return <button onClick={login}>Login</button>;
+ *   }
+ *
+ *   return (
+ *     <div>
+ *       <p>Welcome, {user?.email?.address}!</p>
+ *       <button onClick={logout}>Logout</button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export declare const useAuth: () => UseAuthReturn;

package/dist/hooks/useCanton.d.ts

@@ -0,0 +1,19 @@
+import { CantonContextValue } from '../providers/CantonProvider';
+export type { CantonContextValue as UseCantonReturn };
+/**
+ * Hook for Canton Network operations
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const { isRegistered, registerCanton, sendCantonCoin } = useCanton();
+ *
+ *   if (!isRegistered) {
+ *     return <button onClick={registerCanton}>Register</button>;
+ *   }
+ *
+ *   return <button onClick={() => sendCantonCoin(partyId, "10")}>Send</button>;
+ * }
+ * ```
+ */
+export declare function useCanton(): CantonContextValue;

package/dist/hooks/useConfirmModal.d.ts

@@ -0,0 +1,15 @@
+import { ConfirmModalOptions, SignMessageModalOptions, SignTransactionOptions, ModalResult } from '../providers/SupaProvider';
+export interface UseConfirmModalReturn {
+    /** Show a generic confirmation modal */
+    confirm: (options: ConfirmModalOptions) => Promise<ModalResult>;
+    /** Show a message signing confirmation modal */
+    signMessageConfirm: (options: SignMessageModalOptions) => Promise<ModalResult>;
+    /** Show a transaction signing confirmation modal */
+    signTransactionConfirm: (options: SignTransactionOptions) => Promise<ModalResult>;
+    /** Set loading state for current modal */
+    setModalLoading: (loading: boolean) => void;
+    /** Close current modal */
+    closeModal: () => void;
+}
+export declare function useConfirmModal(): UseConfirmModalReturn;
+export type { ConfirmModalOptions, SignMessageModalOptions, SignTransactionOptions, ModalResult };

package/dist/hooks/useSendTransaction.d.ts

@@ -0,0 +1,27 @@
+import { StellarWallet } from '../utils/stellar';
+import { CantonQueryCompletionResponseDto, CantonSubmitPreparedOptions } from '../services/cantonService';
+export interface SendTransactionOptions {
+    onSuccess?: (result: CantonQueryCompletionResponseDto) => void;
+    onRejection?: () => void;
+    onError?: (error: Error) => void;
+    skipModal?: boolean;
+    modalTitle?: string;
+    modalDescription?: string;
+    modalConfirmText?: string;
+    modalRejectText?: string;
+    /** Custom content to display in modal instead of transaction hash */
+    modalDisplayContent?: string;
+    /** Show technical transaction details (command, contracts, hash) as JSON. Default: false */
+    showTechnicalDetails?: boolean;
+    submitOptions?: CantonSubmitPreparedOptions;
+}
+export interface UseSendTransactionReturn {
+    /** Sign and send a Canton transaction with confirmation modal */
+    sendTransaction: (commands: unknown, disclosedContracts?: unknown, options?: SendTransactionOptions) => Promise<CantonQueryCompletionResponseDto | null>;
+    loading: boolean;
+    error: Error | null;
+    clearError: () => void;
+    stellarWallets: StellarWallet[];
+    stellarWallet: StellarWallet | null;
+}
+export declare function useSendTransaction(): UseSendTransactionReturn;

package/dist/hooks/useSignMessage.d.ts

@@ -0,0 +1,25 @@
+import { StellarWallet } from '../utils/stellar';
+export interface SignMessageOptions {
+    onSuccess?: (signature: string) => void;
+    onRejection?: () => void;
+    onError?: (error: Error) => void;
+    skipModal?: boolean;
+    title?: string;
+    description?: string;
+    confirmText?: string;
+    rejectText?: string;
+    /** Custom content to display in modal instead of message */
+    displayContent?: string;
+    /** Show technical details (address, chainType, hash) as JSON. Default: false */
+    showTechnicalDetails?: boolean;
+}
+export interface UseSignMessageReturn {
+    /** Sign a text message with confirmation modal */
+    signMessage: (message: string, options?: SignMessageOptions) => Promise<string | null>;
+    loading: boolean;
+    error: Error | null;
+    clearError: () => void;
+    stellarWallets: StellarWallet[];
+    stellarWallet: StellarWallet | null;
+}
+export declare function useSignMessage(): UseSignMessageReturn;

package/dist/hooks/useSignRawHashWithModal.d.ts

@@ -0,0 +1,22 @@
+import { useSignRawHash } from '@privy-io/react-auth/extended-chains';
+export interface SignRawHashModalOptions {
+    skipModal?: boolean;
+    title?: string;
+    description?: string;
+    confirmText?: string;
+    rejectText?: string;
+    infoText?: string;
+    /** Custom content to display instead of auto-generated JSON */
+    displayHash?: string;
+    /** Show technical details (address, chainType, hash) as JSON. Default: false */
+    showTechnicalDetails?: boolean;
+}
+type SignRawHashParams = Parameters<ReturnType<typeof useSignRawHash>['signRawHash']>[0];
+export interface UseSignRawHashWithModalReturn {
+    /** Sign a raw hash with confirmation modal */
+    signRawHashWithModal: (params: SignRawHashParams, modalOptions?: SignRawHashModalOptions) => Promise<{
+        signature: string;
+    } | null>;
+}
+export declare function useSignRawHashWithModal(): UseSignRawHashWithModalReturn;
+export {};

package/dist/hooks/useSmartWallets.d.ts

@@ -0,0 +1,16 @@
+import { useSmartWallets as usePrivySmartWallets } from '@privy-io/react-auth/smart-wallets';
+export interface UseSmartWalletsReturn {
+    /** Client for interacting with smart wallets */
+    client: ReturnType<typeof usePrivySmartWallets>['client'];
+    /** Get client for specific chain */
+    getClientForChain: ReturnType<typeof usePrivySmartWallets>['getClientForChain'];
+    /** Get user's smart wallet address */
+    address: string | undefined;
+    /** Whether smart wallets are ready to use */
+    ready: boolean;
+}
+/**
+ * Hook for using Privy Smart Wallets
+ * Must be used within SmartWalletsProvider (automatically enabled in SupaProvider when smartWallets.enabled = true)
+ */
+export declare function useSmartWallets(): UseSmartWalletsReturn;

package/dist/hooks/useStellarWallet.d.ts

@@ -0,0 +1,6 @@
+import { StellarWallet } from '../utils/stellar';
+export interface UseStellarWalletReturn {
+    stellarWallets: StellarWallet[];
+    stellarWallet: StellarWallet | null;
+}
+export declare function useStellarWallet(): UseStellarWalletReturn;

package/dist/hooks/useSupa.d.ts

@@ -0,0 +1,61 @@
+import { UseAuthReturn } from './useAuth';
+import { UseCantonReturn } from './useCanton';
+import { UseAPIReturn } from './useAPI';
+/**
+ * Return type for useSupa hook
+ */
+export interface UseSupaReturn {
+    /** Authentication methods and user state */
+    auth: UseAuthReturn;
+    /** Canton Network operations and wallet management */
+    canton: UseCantonReturn;
+    /** Backend API methods for data access */
+    api: UseAPIReturn;
+    /** Automated onboarding flow (login → create wallet → register Canton) */
+    onboard: () => Promise<void>;
+}
+/**
+ * Main hook for accessing all Supa SDK features
+ * Combines authentication, Canton Network, and API functionality
+ *
+ * Note: Canton state (isRegistered, cantonUser, etc.) is shared across
+ * all components via CantonProvider. No duplicate registration will occur.
+ *
+ * @returns Combined SDK functionality with convenience methods
+ *
+ * @example
+ * Basic usage
+ * ```tsx
+ * function Dashboard() {
+ *   const { auth, canton, api } = useSupa();
+ *
+ *   if (!auth.authenticated) {
+ *     return <button onClick={auth.login}>Login</button>;
+ *   }
+ *
+ *   return (
+ *     <div>
+ *       <p>User: {auth.user?.email?.address}</p>
+ *       <button onClick={() => canton.registerCanton()}>
+ *         Register Canton
+ *       </button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * Using automated onboarding
+ * ```tsx
+ * function OnboardButton() {
+ *   const { onboard, canton } = useSupa();
+ *
+ *   return (
+ *     <button onClick={onboard}>
+ *       {canton.isRegistered ? 'Already registered' : 'Get Started'}
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
+export declare const useSupa: () => UseSupaReturn;