@dubsdotapp/expo 0.1.3 → 0.2.1

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;
 }
@@ -257,6 +264,34 @@ 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 UiConfig {
+    accentColor?: string;
+    appIcon?: string;
+    appName?: string;
+    tagline?: string;
+}
 
 interface DubsClientConfig {
     apiKey: string;
@@ -285,6 +320,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[];
@@ -317,6 +353,8 @@ declare class DubsClient {
     parseErrorLocal(error: unknown): ParsedError;
     /** Get the full local error code map */
     getErrorCodesLocal(): Record<number, SolanaErrorCode>;
+    /** Fetch the app's UI customization config (accent color, icon, tagline) */
+    getAppConfig(): Promise<UiConfig>;
 }
 
 declare class DubsApiError extends Error {
@@ -334,6 +372,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.
@@ -358,21 +418,82 @@ 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;
+    /** Override accent color for registration screens (from developer UI config) */
+    accentColor?: string;
+}
+declare function AuthGate({ children, onSaveToken, onLoadToken, renderLoading, renderError, renderRegistration, appName, accentColor, }: 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;
+    /** Override accent color (e.g. from developer UI config) */
+    accentColor?: string;
+    /** URL to app icon — renders as Image instead of the default letter circle */
+    appIcon?: string;
+    /** Override subtitle text below app name */
+    tagline?: string;
+}
+declare function ConnectWalletScreen({ onConnect, connecting, error, appName, accentColor, appIcon, tagline, }: 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 */
@@ -411,6 +532,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.
      */
@@ -513,35 +636,6 @@ interface UseAuthResult {
 }
 declare function useAuth(): UseAuthResult;
 
-interface RegistrationScreenProps {
-    onRegister: (username: string, referralCode?: string, avatarUrl?: string) => void;
-    registering: boolean;
-    error: Error | null;
-    client: DubsClient;
-}
-interface AuthGateProps {
-    children: React.ReactNode;
-    onSaveToken: (token: string | null) => void | Promise<void>;
-    onLoadToken: () => string | null | Promise<string | null>;
-    renderLoading?: (status: AuthStatus) => React.ReactNode;
-    renderError?: (error: Error, retry: () => void) => React.ReactNode;
-    renderRegistration?: (props: RegistrationScreenProps) => React.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 UserProfileCardProps {
     walletAddress: string;
     username?: string;
@@ -580,16 +674,83 @@ interface DubsTheme {
     errorBorder: string;
 }
 declare function useDubsTheme(): DubsTheme;
+/** Merge overrides into a base theme (e.g. custom accent color from developer config) */
+declare function mergeTheme(base: DubsTheme, overrides: Partial<DubsTheme>): 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 UiConfig, type UnifiedEvent, type UseAuthResult, UserProfileCard, type UserProfileCardProps, type ValidateEventResult, type WalletAdapter, createSecureStoreStorage, mergeTheme, parseSolanaError, signAndSendBase64Transaction, useAuth, useClaim, useCreateGame, useDubs, useDubsTheme, useEvents, useGame, useGames, useJoinGame, useNetworkGames };