@dubsdotapp/expo 0.1.2 → 0.2.0

package/README.md

@@ -5,7 +5,7 @@ React Native SDK for the [Dubs](https://dubs.fun) betting platform. Pure TypeScr
 ## Install
 
 ```bash
-npx expo install @dubsdotapp/expo @solana/web3.js
+npx expo install @dubsdotapp/expo @solana/web3.js expo-secure-store
 ```
 
 For the built-in Mobile Wallet Adapter (optional):
@@ -19,25 +19,38 @@ npx expo install @solana-mobile/mobile-wallet-adapter-protocol-web3js
 ### 1. Set up the provider
 
 ```tsx
-import { DubsProvider, MwaWalletAdapter } from '@dubsdotapp/expo';
-
-const wallet = new MwaWalletAdapter({
-  appIdentity: { name: 'My App' },
-});
+import { DubsProvider } from '@dubsdotapp/expo';
 
 export default function App() {
   return (
-    <DubsProvider
-      apiKey="your_api_key_here"
-      wallet={wallet}
-    >
+    <DubsProvider apiKey="your_api_key_here" appName="My App" network="devnet">
       <HomeScreen />
     </DubsProvider>
   );
 }
 ```
 
-### 2. Browse events
+That's it — 5 lines. `DubsProvider` handles everything:
+
+- **Connect screen** — shows a "Connect Wallet" button, opens Phantom/Solflare/etc.
+- **Silent reconnect** — returning users skip straight to the app
+- **3-step onboarding** — avatar selection (6 DiceBear styles), real-time username validation, optional referral code
+- **Token persistence** — MWA + JWT tokens saved in `expo-secure-store`
+- **Session management** — sign-in, registration, restore, and full disconnect/logout
+
+### 2. Access the user
+
+```tsx
+import { useAuth } from '@dubsdotapp/expo';
+
+function Profile() {
+  const { user, isAuthenticated } = useAuth();
+  if (!isAuthenticated) return null;
+  return <Text>@{user.username}</Text>;
+}
+```
+
+### 3. Browse events
 
 ```tsx
 import { useEvents } from '@dubsdotapp/expo';
@@ -59,7 +72,7 @@ function EventsList() {
 }
 ```
 
-### 3. Create a bet
+### 4. Create a bet
 
 ```tsx
 import { useCreateGame } from '@dubsdotapp/expo';
@@ -88,22 +101,50 @@ function CreateBet({ eventId }: { eventId: string }) {
 }
 ```
 
-## Custom Wallet Adapter
+## Provider Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `apiKey` | `string` | *required* | Your Dubs API key |
+| `appName` | `string` | `'Dubs'` | App name shown on connect/auth screens |
+| `network` | `'devnet' \| 'mainnet-beta'` | `'mainnet-beta'` | Network preset (sets baseUrl, rpcUrl, cluster) |
+| `wallet` | `WalletAdapter` | *auto (MWA)* | Bring your own wallet adapter |
+| `tokenStorage` | `TokenStorage` | *SecureStore* | Custom token persistence |
+| `baseUrl` | `string` | *from network* | Override API base URL |
+| `rpcUrl` | `string` | *from network* | Override Solana RPC URL |
+| `renderConnectScreen` | `fn \| false` | *default UI* | Custom connect screen, or `false` to hide |
+| `renderLoading` | `fn` | *default UI* | Custom loading screen during auth |
+| `renderError` | `fn` | *default UI* | Custom error screen |
+| `renderRegistration` | `fn` | *default UI* | Custom registration screen |
+| `managed` | `boolean` | `true` | Set `false` for headless mode (no connect screen or auth gate) |
+
+### Disconnect
+
+```tsx
+import { useDubs } from '@dubsdotapp/expo';
+
+function LogoutButton() {
+  const { disconnect } = useDubs();
+  return <Button title="Log Out" onPress={disconnect} />;
+}
+```
+
+`disconnect()` clears wallet connection, MWA token, JWT, and returns to the connect screen.
 
-If you're using Privy, Dynamic, or another wallet provider, implement the `WalletAdapter` interface:
+## Custom Wallet Adapter (BYOA)
+
+If you're using Privy, Dynamic, or another wallet provider, pass a `wallet` prop to skip managed MWA:
 
 ```tsx
 import { DubsProvider } from '@dubsdotapp/expo';
 import type { WalletAdapter } from '@dubsdotapp/expo';
-import { Transaction, PublicKey } from '@solana/web3.js';
 
 const myAdapter: WalletAdapter = {
   publicKey: new PublicKey('...'),
   connected: true,
-  signTransaction: async (tx: Transaction) => {
-    // Sign using your wallet provider
-    return signedTx;
-  },
+  signTransaction: async (tx) => { /* ... */ return signedTx; },
+  connect: async () => { /* ... */ },
+  disconnect: () => { /* ... */ },
 };
 
 <DubsProvider apiKey="..." wallet={myAdapter}>
@@ -111,6 +152,26 @@ const myAdapter: WalletAdapter = {
 </DubsProvider>
 ```
 
+## Custom Token Storage
+
+By default, `DubsProvider` uses `expo-secure-store` for persisting auth tokens. To use a different storage:
+
+```tsx
+import { DubsProvider } from '@dubsdotapp/expo';
+import type { TokenStorage } from '@dubsdotapp/expo';
+import AsyncStorage from '@react-native-async-storage/async-storage';
+
+const myStorage: TokenStorage = {
+  getItem: (key) => AsyncStorage.getItem(key),
+  setItem: (key, value) => AsyncStorage.setItem(key, value),
+  deleteItem: (key) => AsyncStorage.removeItem(key),
+};
+
+<DubsProvider apiKey="..." tokenStorage={myStorage}>
+  <App />
+</DubsProvider>
+```
+
 ## API Reference
 
 ### Hooks

package/dist/index.d.mts

@@ -1,6 +1,6 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
-import React from 'react';
-import { PublicKey, Transaction, Connection, TransactionConfirmationStatus } from '@solana/web3.js';
+import React$1 from 'react';
+import { PublicKey, Transaction, Connection } from '@solana/web3.js';
 
 interface Opponent {
     name: string | null;
@@ -128,6 +128,13 @@ interface GameMedia {
     poster: string | null;
     thumbnail: string | null;
 }
+interface Bettor {
+    wallet: string;
+    username: string | null;
+    avatar: string | null;
+    team: 'home' | 'away' | 'draw';
+    amount: number;
+}
 interface GameDetail {
     gameId: string;
     gameAddress: string;
@@ -137,15 +144,14 @@ interface GameDetail {
     isLocked: boolean;
     isResolved: boolean;
     status: string;
+    league: string | null;
     lockTimestamp: number | null;
-    homePlayers: string[];
-    awayPlayers: string[];
-    drawPlayers: string[];
+    opponents: GameListOpponent[];
+    bettors: Bettor[];
     homePool: number;
     awayPool: number;
     drawPool: number;
     totalPool: number;
-    sportsEvent: Record<string, unknown> | null;
     media: GameMedia;
     createdAt: string;
     updatedAt: string;
@@ -177,6 +183,7 @@ interface GetGamesParams {
 }
 interface GetNetworkGamesParams {
     league?: string;
+    exclude_wallet?: string;
     limit?: number;
     offset?: number;
 }
@@ -232,6 +239,7 @@ interface RegisterParams {
     nonce: string;
     username: string;
     referralCode?: string;
+    avatarUrl?: string;
 }
 interface RegisterResult {
     user: DubsUser;
@@ -256,6 +264,28 @@ interface MutationResult<TParams, TResult> {
     data: TResult | null;
     reset: () => void;
 }
+interface LiveScoreCompetitor {
+    name: string;
+    homeAway: 'home' | 'away';
+    score: number;
+    logo: string | null;
+    abbreviation: string;
+}
+interface LiveScore {
+    status: string;
+    period: number | null;
+    displayClock: string | null;
+    detail: string | null;
+    shortDetail: string | null;
+    competitors: LiveScoreCompetitor[];
+    ufcData?: {
+        currentRound: number;
+        totalRounds: number;
+        clock: string;
+        fightState: string;
+        statusDetail: string;
+    };
+}
 
 interface DubsClientConfig {
     apiKey: string;
@@ -284,6 +314,7 @@ declare class DubsClient {
     confirmGame(params: ConfirmGameParams): Promise<ConfirmGameResult>;
     buildClaimTransaction(params: BuildClaimParams): Promise<BuildClaimResult>;
     getGame(gameId: string): Promise<GameDetail>;
+    getLiveScore(gameId: string): Promise<LiveScore | null>;
     getGames(params?: GetGamesParams): Promise<GameListItem[]>;
     getNetworkGames(params?: GetNetworkGamesParams): Promise<{
         games: GameListItem[];
@@ -333,6 +364,28 @@ declare function parseSolanaError(err: unknown): ParsedError;
 
 declare const DEFAULT_BASE_URL = "https://dubs-server-prod-9c91d3f01199.herokuapp.com/api/developer/v1";
 declare const DEFAULT_RPC_URL = "https://api.mainnet-beta.solana.com";
+type DubsNetwork = 'devnet' | 'mainnet-beta';
+declare const NETWORK_CONFIG: Record<DubsNetwork, {
+    baseUrl: string;
+    rpcUrl: string;
+    cluster: string;
+}>;
+
+interface TokenStorage {
+    getItem(key: string): Promise<string | null>;
+    setItem(key: string, value: string): Promise<void>;
+    deleteItem(key: string): Promise<void>;
+}
+declare const STORAGE_KEYS: {
+    readonly MWA_AUTH_TOKEN: "dubs_mwa_auth_token";
+    readonly JWT_TOKEN: "dubs_jwt_token";
+};
+/**
+ * Creates a TokenStorage backed by expo-secure-store.
+ * Lazy-imports the module so it's only required at runtime when actually used.
+ * Throws a clear error if expo-secure-store is not installed.
+ */
+declare function createSecureStoreStorage(): TokenStorage;
 
 /**
  * Minimal wallet adapter interface.
@@ -357,21 +410,74 @@ interface WalletAdapter {
      * Returns the signature as a Uint8Array.
      */
     signMessage?(message: Uint8Array): Promise<Uint8Array>;
+    /** Optional: Connect the wallet */
+    connect?(): Promise<void>;
+    /** Optional: Disconnect the wallet */
+    disconnect?(): void | Promise<void>;
+}
+
+interface RegistrationScreenProps {
+    onRegister: (username: string, referralCode?: string, avatarUrl?: string) => void;
+    registering: boolean;
+    error: Error | null;
+    client: DubsClient;
+}
+interface AuthGateProps {
+    children: React$1.ReactNode;
+    onSaveToken: (token: string | null) => void | Promise<void>;
+    onLoadToken: () => string | null | Promise<string | null>;
+    renderLoading?: (status: AuthStatus) => React$1.ReactNode;
+    renderError?: (error: Error, retry: () => void) => React$1.ReactNode;
+    renderRegistration?: (props: RegistrationScreenProps) => React$1.ReactNode;
+    appName?: string;
 }
+declare function AuthGate({ children, onSaveToken, onLoadToken, renderLoading, renderError, renderRegistration, appName, }: AuthGateProps): react_jsx_runtime.JSX.Element;
+
+interface ConnectWalletScreenProps {
+    /** Called when the user taps Connect Wallet */
+    onConnect: () => void | Promise<void>;
+    /** Show a loading spinner on the button while connecting */
+    connecting?: boolean;
+    /** Error message to display (e.g. "User rejected the request") */
+    error?: string | null;
+    /** App name shown in the header. Defaults to "Dubs" */
+    appName?: string;
+}
+declare function ConnectWalletScreen({ onConnect, connecting, error, appName, }: ConnectWalletScreenProps): react_jsx_runtime.JSX.Element;
 
 interface DubsContextValue {
     client: DubsClient;
     wallet: WalletAdapter;
     connection: Connection;
+    appName: string;
+    network: DubsNetwork;
+    disconnect: () => Promise<void>;
 }
 interface DubsProviderProps {
     apiKey: string;
+    children: React$1.ReactNode;
+    appName?: string;
+    network?: DubsNetwork;
+    /** Escape hatch: bring your own wallet adapter. Disables managed MWA. */
+    wallet?: WalletAdapter;
+    /** Escape hatch: custom token persistence. Defaults to expo-secure-store. */
+    tokenStorage?: TokenStorage;
+    /** Escape hatch: override base URL (takes precedence over network). */
     baseUrl?: string;
+    /** Escape hatch: override RPC URL (takes precedence over network). */
     rpcUrl?: string;
-    wallet: WalletAdapter;
-    children: React.ReactNode;
-}
-declare function DubsProvider({ apiKey, baseUrl, rpcUrl, wallet, children }: DubsProviderProps): react_jsx_runtime.JSX.Element;
+    /** Custom connect screen, or false to hide it entirely (headless mode). */
+    renderConnectScreen?: ((props: ConnectWalletScreenProps) => React$1.ReactNode) | false;
+    /** Custom loading screen shown during auth. */
+    renderLoading?: (status: AuthStatus) => React$1.ReactNode;
+    /** Custom error screen shown on auth failure. */
+    renderError?: (error: Error, retry: () => void) => React$1.ReactNode;
+    /** Custom registration screen. */
+    renderRegistration?: (props: RegistrationScreenProps) => React$1.ReactNode;
+    /** Set to false to skip AuthGate and connect screen (headless/BYOA mode). Default: true. */
+    managed?: boolean;
+}
+declare function DubsProvider({ apiKey, children, appName, network, wallet: externalWallet, tokenStorage, baseUrl: baseUrlOverride, rpcUrl: rpcUrlOverride, renderConnectScreen, renderLoading, renderError, renderRegistration, managed, }: DubsProviderProps): react_jsx_runtime.JSX.Element;
 declare function useDubs(): DubsContextValue;
 
 /** The `transact` function signature from @solana-mobile/mobile-wallet-adapter-protocol-web3js */
@@ -410,6 +516,8 @@ declare class MwaWalletAdapter implements WalletAdapter {
     constructor(config: MwaAdapterConfig);
     get publicKey(): PublicKey | null;
     get connected(): boolean;
+    get authToken(): string | null;
+    setAuthToken(token: string | null): void;
     /**
      * Connect to a mobile wallet. Call this before any signing.
      */
@@ -499,7 +607,7 @@ interface UseAuthResult {
      * Register a new user after authenticate() returned needsRegistration.
      * Reuses the nonce+signature from authenticate() — no second signing prompt.
      */
-    register: (username: string, referralCode?: string) => Promise<void>;
+    register: (username: string, referralCode?: string, avatarUrl?: string) => Promise<void>;
     /** Log out and clear state */
     logout: () => Promise<void>;
     /**
@@ -512,45 +620,6 @@ interface UseAuthResult {
 }
 declare function useAuth(): UseAuthResult;
 
-interface RegistrationScreenProps {
-    /** Called when the user submits registration */
-    onRegister: (username: string, referralCode?: string) => void;
-    /** Whether a registration request is in flight */
-    registering: boolean;
-    /** Error from the last registration attempt, or null */
-    error: Error | null;
-    /** DubsClient instance for checkUsername() availability checks */
-    client: DubsClient;
-}
-interface AuthGateProps {
-    children: React.ReactNode;
-    /** Persist or clear the JWT token (called with null on logout) */
-    onSaveToken: (token: string | null) => void | Promise<void>;
-    /** Load a previously persisted JWT token */
-    onLoadToken: () => string | null | Promise<string | null>;
-    /** Custom loading screen (receives current auth status) */
-    renderLoading?: (status: AuthStatus) => React.ReactNode;
-    /** Custom error screen (receives the error and a retry callback) */
-    renderError?: (error: Error, retry: () => void) => React.ReactNode;
-    /** Custom registration screen */
-    renderRegistration?: (props: RegistrationScreenProps) => React.ReactNode;
-    /** App name shown in default screens. Defaults to "Dubs" */
-    appName?: string;
-}
-declare function AuthGate({ children, onSaveToken, onLoadToken, renderLoading, renderError, renderRegistration, appName, }: AuthGateProps): react_jsx_runtime.JSX.Element;
-
-interface ConnectWalletScreenProps {
-    /** Called when the user taps Connect Wallet */
-    onConnect: () => void | Promise<void>;
-    /** Show a loading spinner on the button while connecting */
-    connecting?: boolean;
-    /** Error message to display (e.g. "User rejected the request") */
-    error?: string | null;
-    /** App name shown in the header. Defaults to "Dubs" */
-    appName?: string;
-}
-declare function ConnectWalletScreen({ onConnect, connecting, error, appName, }: ConnectWalletScreenProps): react_jsx_runtime.JSX.Element;
-
 interface UserProfileCardProps {
     walletAddress: string;
     username?: string;
@@ -590,15 +659,80 @@ interface DubsTheme {
 }
 declare function useDubsTheme(): DubsTheme;
 
+interface GamePosterProps {
+    game: GameDetail;
+    /** Optional Image component — pass expo-image or RN Image. Defaults to RN Image. */
+    ImageComponent?: React.ComponentType<any>;
+}
 /**
- * Deserialize a base64-encoded transaction, sign via wallet adapter, send to Solana.
- * Returns the transaction signature.
+ * Matchup poster hero widget.
+ * Shows the game poster image (or team logo fallback), countdown pill, and pool total.
+ */
+declare function GamePoster({ game, ImageComponent }: GamePosterProps): react_jsx_runtime.JSX.Element;
+
+interface LivePoolsCardProps {
+    game: GameDetail;
+    /** Custom short-name function for team labels. Defaults to full name. */
+    shortName?: (name: string | null) => string;
+    /** Override bar colors. Defaults to blue/red. */
+    homeColor?: string;
+    awayColor?: string;
+}
+/**
+ * Pool breakdown card showing each side's SOL amount, bar chart, and implied odds.
+ */
+declare function LivePoolsCard({ game, shortName, homeColor, awayColor, }: LivePoolsCardProps): react_jsx_runtime.JSX.Element;
+
+interface PickWinnerCardProps {
+    game: GameDetail;
+    selectedTeam: 'home' | 'away' | null;
+    onSelect: (team: 'home' | 'away') => void;
+    /** Custom short-name function for team labels. Defaults to full name. */
+    shortName?: (name: string | null) => string;
+    /** Override colors. Defaults to blue/red. */
+    homeColor?: string;
+    awayColor?: string;
+    /** Optional Image component (expo-image, etc.). */
+    ImageComponent?: React.ComponentType<any>;
+}
+/**
+ * Team selection card for picking which side to bet on.
+ */
+declare function PickWinnerCard({ game, selectedTeam, onSelect, shortName, homeColor, awayColor, ImageComponent, }: PickWinnerCardProps): react_jsx_runtime.JSX.Element;
+
+interface PlayersCardProps {
+    game: GameDetail;
+    /** How many chars to show on each side of a truncated wallet. Default 4. */
+    truncateChars?: number;
+    /** Override team dot colors. */
+    homeColor?: string;
+    awayColor?: string;
+    drawColor?: string;
+    /** Optional Image component (expo-image, etc.). */
+    ImageComponent?: React.ComponentType<any>;
+}
+/**
+ * Card showing all bettors in a game with their avatar, username, team, and wager amount.
  */
-declare function signAndSendBase64Transaction(base64Tx: string, wallet: WalletAdapter, connection: Connection): Promise<string>;
+declare function PlayersCard({ game, truncateChars, homeColor, awayColor, drawColor, ImageComponent, }: PlayersCardProps): react_jsx_runtime.JSX.Element;
+
+interface JoinGameButtonProps {
+    game: GameDetail;
+    walletAddress: string;
+    selectedTeam: 'home' | 'away' | null;
+    status: MutationStatus;
+    onJoin: () => void;
+}
 /**
- * Poll for transaction confirmation using getSignatureStatuses.
- * Uses polling instead of deprecated WebSocket-based confirmTransaction.
+ * Fixed bottom bar with buy-in info and join button.
+ * Renders nothing if the user already joined, or the game is locked/resolved.
+ */
+declare function JoinGameButton({ game, walletAddress, selectedTeam, status, onJoin }: JoinGameButtonProps): react_jsx_runtime.JSX.Element | null;
+
+/**
+ * Deserialize a base64-encoded transaction, sign via wallet adapter, send to Solana.
+ * Returns the transaction signature.
  */
-declare function pollTransactionConfirmation(signature: string, connection: Connection, commitment?: TransactionConfirmationStatus, timeout?: number, interval?: number): Promise<void>;
+declare function signAndSendBase64Transaction(base64Tx: string, wallet: WalletAdapter): Promise<string>;
 
-export { AuthGate, type AuthGateProps, type AuthStatus, type AuthenticateParams, type AuthenticateResult, type BuildClaimParams, type BuildClaimResult, type CheckUsernameResult, type ClaimMutationResult, type ConfirmGameParams, type ConfirmGameResult, ConnectWalletScreen, type ConnectWalletScreenProps, type CreateGameMutationResult, type CreateGameParams, type CreateGameResult, DEFAULT_BASE_URL, DEFAULT_RPC_URL, DubsApiError, type DubsAppUser, DubsClient, type DubsClientConfig, type DubsContextValue, DubsProvider, type DubsProviderProps, type DubsPublicUser, type DubsTheme, type DubsUser, type EsportsMatchDetail, type EsportsMatchOpponent, type EsportsMatchResult, type EventMedia, type EventMeta, type EventStream, type GameDetail, type GameListItem, type GameListOpponent, type GameMedia, type GetGamesParams, type GetNetworkGamesParams, type GetUpcomingEventsParams, type JoinGameMutationResult, type JoinGameParams, type JoinGameResult, type MutationResult, type MutationStatus, type MwaAdapterConfig, type MwaTransactFn, MwaWalletAdapter, type NonceResult, type Opponent, type Pagination, type ParsedError, type QueryResult, type RegisterParams, type RegisterResult, type RegistrationScreenProps, SOLANA_PROGRAM_ERRORS, SettingsSheet, type SettingsSheetProps, type SolanaErrorCode, type UnifiedEvent, type UseAuthResult, UserProfileCard, type UserProfileCardProps, type ValidateEventResult, type WalletAdapter, parseSolanaError, pollTransactionConfirmation, signAndSendBase64Transaction, useAuth, useClaim, useCreateGame, useDubs, useDubsTheme, useEvents, useGame, useGames, useJoinGame, useNetworkGames };
+export { AuthGate, type AuthGateProps, type AuthStatus, type AuthenticateParams, type AuthenticateResult, type Bettor, type BuildClaimParams, type BuildClaimResult, type CheckUsernameResult, type ClaimMutationResult, type ConfirmGameParams, type ConfirmGameResult, ConnectWalletScreen, type ConnectWalletScreenProps, type CreateGameMutationResult, type CreateGameParams, type CreateGameResult, DEFAULT_BASE_URL, DEFAULT_RPC_URL, DubsApiError, type DubsAppUser, DubsClient, type DubsClientConfig, type DubsContextValue, type DubsNetwork, DubsProvider, type DubsProviderProps, type DubsPublicUser, type DubsTheme, type DubsUser, type EsportsMatchDetail, type EsportsMatchOpponent, type EsportsMatchResult, type EventMedia, type EventMeta, type EventStream, type GameDetail, type GameListItem, type GameListOpponent, type GameMedia, GamePoster, type GamePosterProps, type GetGamesParams, type GetNetworkGamesParams, type GetUpcomingEventsParams, JoinGameButton, type JoinGameButtonProps, type JoinGameMutationResult, type JoinGameParams, type JoinGameResult, LivePoolsCard, type LivePoolsCardProps, type LiveScore, type LiveScoreCompetitor, type MutationResult, type MutationStatus, type MwaAdapterConfig, type MwaTransactFn, MwaWalletAdapter, NETWORK_CONFIG, type NonceResult, type Opponent, type Pagination, type ParsedError, PickWinnerCard, type PickWinnerCardProps, PlayersCard, type PlayersCardProps, type QueryResult, type RegisterParams, type RegisterResult, type RegistrationScreenProps, SOLANA_PROGRAM_ERRORS, STORAGE_KEYS, SettingsSheet, type SettingsSheetProps, type SolanaErrorCode, type TokenStorage, type UnifiedEvent, type UseAuthResult, UserProfileCard, type UserProfileCardProps, type ValidateEventResult, type WalletAdapter, createSecureStoreStorage, parseSolanaError, signAndSendBase64Transaction, useAuth, useClaim, useCreateGame, useDubs, useDubsTheme, useEvents, useGame, useGames, useJoinGame, useNetworkGames };