@pollar/react 0.7.1 → 0.8.0

package/dist/index.d.ts

@@ -1,10 +1,27 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
-import { PollarApplicationConfigContent, PollarLoginOptions, PollarClientConfig, pollarPaths, PollarAdapters, PollarClient, TransactionState, TxBuildBody, WalletId, StellarNetwork, WalletBalanceState, TxHistoryState, PollarAdapter, KycStatus as KycStatus$1, RampQuote, AuthState, KycProvider, KycStartResponse, RampDirection, PaymentInstructions, WalletBalanceRecord, SessionInfo, DistributionRulesState, DistributionRule } from '@pollar/core';
+import { PollarApplicationConfigContent, PollarLoginOptions, PollarClientConfig, WalletId, AuthState, pollarPaths, PollarClient, PollarAdapters, OnStorageDegrade, TransactionState, TxBuildBody, BuildOutcome, SubmitOutcome, SignOutcome, StellarNetwork, WalletBalanceState, TxHistoryState, PollarAdapter, KycStatus as KycStatus$1, RampQuote, KycProvider, KycStartResponse, RampDirection, PaymentInstructions, WalletBalanceRecord, SessionInfo, DistributionRulesState, DistributionRule } from '@pollar/core';
 import { ReactNode } from 'react';
 
 type ConfigResponse = pollarPaths['/applications/config']['get']['responses'][200]['content']['application/json'];
 type PollarConfig = ConfigResponse['content'];
 type PollarStyles = PollarConfig['styles'];
+/**
+ * Props passed by `@pollar/react` to a `renderWallets` slot. External wallet
+ * picker components receive these and call `onConnect(id)` when the user picks
+ * a wallet; `@pollar/react` wraps that into `client.loginWallet(id)`.
+ */
+interface RenderWalletsProps {
+    /** Wrapper around `client.loginWallet(id)`. */
+    onConnect: (id: WalletId) => void;
+    /** Current auth state — picker can disable buttons / surface loading. */
+    authState: AuthState;
+}
+/**
+ * Signature for the `ui.renderWallets` slot on `<PollarProvider>`. When
+ * provided, replaces the default Freighter/Albedo buttons in the LoginModal
+ * with whatever the slot returns (typically a kit-powered wallet grid).
+ */
+type RenderWalletsSlot = (props: RenderWalletsProps) => ReactNode;
 interface AuthProviderProps {
     config: PollarClientConfig;
     children: React.ReactNode;
@@ -39,10 +56,19 @@ interface PollarContextValue {
     openSessionsModal: () => void;
     appConfig: PollarConfig;
     styles: PollarStyles;
+    /** UI slot for wallet picker (forwarded from provider props). */
+    renderWallets?: RenderWalletsSlot;
     openTxModal: () => void;
     tx: TransactionState;
-    buildTx: (operation: TxBuildBody['operation'], params: TxBuildBody['params'], options?: TxBuildBody['options']) => Promise<void>;
-    signAndSubmitTx: (unsignedXdr: string) => Promise<void>;
+    buildTx: (operation: TxBuildBody['operation'], params: TxBuildBody['params'], options?: TxBuildBody['options']) => Promise<BuildOutcome>;
+    signAndSubmitTx: (unsignedXdr: string) => Promise<SubmitOutcome>;
+    /** External-wallet only. Custodial flows should use `signAndSubmitTx`. */
+    signTx: (unsignedXdr: string) => Promise<SignOutcome>;
+    submitTx: (signedXdr: string) => Promise<SubmitOutcome>;
+    /** One-shot: build → sign → submit. Drives the same TransactionState flow as the split calls. */
+    buildAndSignAndSubmitTx: (operation: TxBuildBody['operation'], params: TxBuildBody['params'], options?: TxBuildBody['options']) => Promise<SubmitOutcome>;
+    /** Alias of `buildAndSignAndSubmitTx`. */
+    runTx: (operation: TxBuildBody['operation'], params: TxBuildBody['params'], options?: TxBuildBody['options']) => Promise<SubmitOutcome>;
     walletType: WalletId | null;
     network: StellarNetwork;
     setNetwork: (network: StellarNetwork) => void;
@@ -63,16 +89,45 @@ interface PollarContextValue {
     adapters?: PollarAdapters;
 }
 interface PollarProviderProps {
-    config: PollarClientConfig;
-    styles?: PollarStyles;
+    /**
+     * Either a pre-built `PollarClient` instance (useful for testing or for
+     * reusing the same client outside React) or a `PollarClientConfig` that the
+     * provider will use to construct one on mount.
+     *
+     * The client is locked at first render: changing this prop afterwards is
+     * ignored. To swap clients, unmount and remount the provider.
+     */
+    client: PollarClient | PollarClientConfig;
+    /**
+     * Local override of the `/applications/config` response. If provided (even
+     * `{}`), the remote fetch is skipped and missing fields fall back to the
+     * defaults in `LoginModalTemplate`. If `undefined`, the SDK fetches
+     * `/applications/config` on mount.
+     */
+    appConfig?: PollarConfig;
+    /** UI customization slots. */
+    ui?: {
+        /** Replaces the default Freighter/Albedo wallet picker. */
+        renderWallets?: RenderWalletsSlot;
+    };
     adapters?: PollarAdapters;
+    /**
+     * Notified when persistent storage silently degrades to in-memory mode
+     * (Safari private browsing quota errors, sandboxed iframes, etc.). Use this
+     * to surface a UI hint that the session won't survive a reload, log to
+     * telemetry, or fall back to a different storage strategy.
+     *
+     * Fires at most once per provider lifetime; late mounts get the latched
+     * state replayed on subscribe.
+     */
+    onStorageDegrade?: OnStorageDegrade;
     children: ReactNode;
 }
-declare function PollarProvider({ config, styles: propStyles, adapters, children }: PollarProviderProps): react_jsx_runtime.JSX.Element;
+declare function PollarProvider({ client, appConfig: appConfigProp, ui, adapters, onStorageDegrade, children, }: PollarProviderProps): react_jsx_runtime.JSX.Element;
 declare function usePollar(): PollarContextValue;
 
 type WrappedAdapter<T extends PollarAdapter> = {
-    [K in keyof T]: (params: Parameters<T[K]>[0]) => Promise<void>;
+    [K in keyof T]: (params: Parameters<T[K]>[0]) => Promise<SubmitOutcome>;
 };
 declare function createPollarAdapterHook<T extends PollarAdapter>(key: string): () => WrappedAdapter<T>;
 
@@ -149,8 +204,9 @@ interface LoginModalTemplateProps {
     onEmailChange?: (email: string) => void;
     onEmailSubmit?: () => void;
     onSocialLogin?: (provider: 'google' | 'github') => void;
-    onFreighterConnect?: () => void;
-    onAlbedoConnect?: () => void;
+    onWalletConnect: (id: WalletId) => void;
+    /** Optional override for the wallet picker view. Defaults to a Freighter+Albedo list. */
+    renderWallets?: RenderWalletsSlot;
     authState: AuthState;
     codeInputKey?: number;
     onCodeSubmit?: (code: string) => void;
@@ -158,7 +214,7 @@ interface LoginModalTemplateProps {
     onCancel: () => void;
     onRetry: () => void;
 }
-declare function LoginModalTemplate({ theme, accentColor, logoUrl, emailEnabled, embeddedWallets, providers, appName, email, onEmailChange, onEmailSubmit, onSocialLogin, onFreighterConnect, onAlbedoConnect, authState, codeInputKey, onCodeSubmit, onBack, onCancel, onRetry, }: LoginModalTemplateProps): react_jsx_runtime.JSX.Element;
+declare function LoginModalTemplate({ theme, accentColor, logoUrl, emailEnabled, embeddedWallets, providers, appName, email, onEmailChange, onEmailSubmit, onSocialLogin, onWalletConnect, renderWallets, authState, codeInputKey, onCodeSubmit, onBack, onCancel, onRetry, }: LoginModalTemplateProps): react_jsx_runtime.JSX.Element;
 
 type KycStep = 'select_provider' | 'verifying' | 'polling' | 'done';
 interface KycModalTemplateProps {
@@ -330,4 +386,4 @@ interface DistributionRulesModalTemplateProps {
 }
 declare function DistributionRulesModalTemplate({ theme, accentColor, state, claimingId, claimErrors, claimedIds, onRefresh, onClaim, onClose, }: DistributionRulesModalTemplateProps): react_jsx_runtime.JSX.Element;
 
-export { type AuthContextValue, type AuthModalProps, type AuthProviderProps, DistributionRulesModal, DistributionRulesModalTemplate, KycModal, KycModalTemplate, KycStatus, type KycStep, type LoginButtonProps, LoginModalTemplate, type PollarConfig, PollarProvider, type PollarStyles, type RampStep, RampWidget, RampWidgetTemplate, ReceiveModal, ReceiveModalTemplate, type ReceiveModalTemplateProps, RouteDisplay, SendModal, SendModalTemplate, type SendModalTemplateProps, SessionsModal, SessionsModalTemplate, type SessionsModalTemplateProps, type SessionsState, TransactionModalTemplate, type TransactionModalTemplateProps, TxHistoryModalTemplate, TxStatusView, type TxStatusViewProps, WalletBalanceModal, WalletBalanceModalTemplate, type WalletBalanceModalTemplateProps, WalletButton, createPollarAdapterHook, usePollar };
+export { type AuthContextValue, type AuthModalProps, type AuthProviderProps, DistributionRulesModal, DistributionRulesModalTemplate, KycModal, KycModalTemplate, KycStatus, type KycStep, type LoginButtonProps, LoginModalTemplate, type PollarConfig, PollarProvider, type PollarStyles, type RampStep, RampWidget, RampWidgetTemplate, ReceiveModal, ReceiveModalTemplate, type ReceiveModalTemplateProps, type RenderWalletsProps, type RenderWalletsSlot, RouteDisplay, SendModal, SendModalTemplate, type SendModalTemplateProps, SessionsModal, SessionsModalTemplate, type SessionsModalTemplateProps, type SessionsState, TransactionModalTemplate, type TransactionModalTemplateProps, TxHistoryModalTemplate, TxStatusView, type TxStatusViewProps, WalletBalanceModal, WalletBalanceModalTemplate, type WalletBalanceModalTemplateProps, WalletButton, createPollarAdapterHook, usePollar };