@accesly/react 1.2.0 → 1.3.0

package/dist/index.d.cts

@@ -736,12 +736,21 @@ interface WalletStreamBalancePayload {
     readonly xlm: string;
 }
 /**
- * Activity emitida por el backend ya **filtrada y tipada** — solo eventos
- * relevantes para una wallet de Accesly (rotación de signers + transfers
- * IN/OUT de XLM). Otros eventos on-chain (debug, errores host, eventos
- * irrelevantes) se descartan en el server.
+ * Activity tipada lista para renderizar. Cuatro variants:
+ *
+ *  - `wallet-created`  — deploy inicial del Smart Account.
+ *  - `signer-rotated`  — rotación de signer (recovery).
+ *  - `transfer-in`     — recibió XLM.
+ *  - `transfer-out`    — envió XLM.
+ *
+ * Otros eventos on-chain (signer_added/removed internos, ruido) se descartan.
  */
 type WalletActivityItem = {
+    readonly type: 'wallet-created';
+    readonly txHash: string;
+    readonly ledger: number;
+    readonly timestamp: string | null;
+} | {
     readonly type: 'signer-rotated';
     readonly txHash: string;
     readonly ledger: number;
@@ -808,6 +817,77 @@ interface UseWalletActivityResult {
 }
 declare function useWalletActivity(walletAddress?: string | null, opts?: UseWalletActivityOptions): UseWalletActivityResult;
 
+/**
+ * Cliente y decoder de la **Stellar Expert public API** (indexer free, full
+ * retention, CORS abierto). Es la fuente primaria de `useWalletHistory`.
+ *
+ * Endpoints usados:
+ *   - GET /contract/{walletAddress}/events  — Smart Account events (rotaciones).
+ *   - GET /contract/{xlmSac}/events?topics=transfer
+ *         — Todos los transfers del SAC. Filtramos client-side por wallet.
+ *   - GET /contract/{walletAddress}          — Metadata del wallet (creación).
+ *
+ * Rate limit anonymous: ~1 req/s. Para zaramos cross-tab via BroadcastChannel
+ * en el hook que consume este módulo.
+ */
+
+type StellarExpertNetwork = 'testnet' | 'mainnet';
+
+/**
+ * `useWalletHistory(walletAddress?, opts?)` — historial completo de la wallet
+ * con Stellar Expert como indexer primario y opcional Soroban RPC autenticado
+ * para tail real-time.
+ *
+ * Características:
+ *  - 100% client-side, sin backend custom.
+ *  - Historia completa (mes+) gracias a la retention de Stellar Expert.
+ *  - Cache en `localStorage` per-wallet con TTL 12h → return instantáneo entre
+ *    page reloads y route changes.
+ *  - Polling cada 30s para nuevos events. Pausa si tab oculta.
+ *  - `BroadcastChannel` cross-tab para compartir SE rate limit — solo UN tab
+ *    hace fetch; los demás escuchan el resultado.
+ *  - Optimistic updates: el SDK puede llamar `historyOptimisticPush(addr, item)`
+ *    cuando acaba de mandar una tx exitosa para que aparezca inmediato sin
+ *    esperar el indexing de SE (~30-60s típico).
+ *  - Override de Soroban RPC: pasa `{ sorobanRpcUrl, sorobanRpcAuth }` para
+ *    que el tail (últimos eventos) venga via RPC con tu API key — sin lag.
+ */
+
+/**
+ * Inyecta un item de history "optimistically" — útil cuando acabás de hacer
+ * `tx.send` y querés que aparezca al instante sin esperar el indexing de SE.
+ * El item queda en memoria hasta que el próximo fetch del hook lo descarte
+ * (porque ya está en el feed real) o hasta `clearOptimistic(walletAddress)`.
+ *
+ * Usado internamente por `tx.send`; expuesto al integrador para casos custom.
+ */
+declare function historyOptimisticPush(walletAddress: string, item: WalletActivityItem): void;
+declare function historyClearOptimistic(walletAddress: string): void;
+interface UseWalletHistoryOptions {
+    /** `'testnet'` (default) o `'mainnet'`. */
+    readonly network?: StellarExpertNetwork;
+    /** Intervalo de poll para nuevos events (ms). Default 30s, 0 desactiva. */
+    readonly pollIntervalMs?: number;
+    /**
+     * Override del Soroban RPC para tail real-time. Si se provee, el hook usa
+     * tu RPC autenticado en vez de hacer poll a Stellar Expert para detectar
+     * nuevos events. Recomendado para producción.
+     */
+    readonly sorobanRpcUrl?: string;
+    readonly sorobanRpcAuth?: string;
+    /** Cantidad de transfers del XLM_SAC a scan-ear por fetch. Default 50. */
+    readonly transferScanLimit?: number;
+}
+interface UseWalletHistoryResult {
+    readonly events: readonly WalletActivityItem[];
+    readonly isLoading: boolean;
+    readonly error: Error | null;
+    readonly hasMore: boolean;
+    loadMore(): Promise<void>;
+    refresh(): Promise<void>;
+}
+declare function useWalletHistory(walletAddress?: string | null, opts?: UseWalletHistoryOptions): UseWalletHistoryResult;
+
 /**
  * @accesly/react — React Provider + `useAccesly` hook.
  *
@@ -832,4 +912,4 @@ declare function useWalletActivity(walletAddress?: string | null, opts?: UseWall
  */
 declare const REACT_ADAPTER_VERSION = "0.0.0";
 
-export { AcceslyContext, type AcceslyContextValue, type AcceslyHook, AcceslyProvider, type AcceslyProviderProps, type AuthNamespace, type BootstrapWalletInput, type CreateWalletInput, type CreatedWalletInfo, ENVIRONMENT_DEFAULTS, type EnsureWalletResult, type EnvironmentDefaults, type FinalizeRecoveryInput, type FinalizeRecoveryResult, type KycNamespace, NotImplementedYetError, REACT_ADAPTER_VERSION, type ReconstructedSeed, type RecoveryNamespace, type RemoteWalletInfo, type RetryDeployResult, type SendXlmInput, type SendXlmResult, type SessionNamespace, type SettingsNamespace, type TxNamespace, type UnlockedSigningMaterial, type UseBalanceResult, type UseWalletActivityOptions, type UseWalletActivityResult, type UseWalletStatusResult, type WalletActivityItem, type WalletNamespace, type WalletStatus, type WalletStatusValue, type WalletStreamActivityPayload, type WalletStreamBalancePayload, type WalletStreamEventType, type WalletStreamStatusPayload, type YieldNamespace, closeAllWalletSubscriptions, subscribeToWalletEvent, useAccesly, useBalance, useWalletActivity, useWalletStatus };
+export { AcceslyContext, type AcceslyContextValue, type AcceslyHook, AcceslyProvider, type AcceslyProviderProps, type AuthNamespace, type BootstrapWalletInput, type CreateWalletInput, type CreatedWalletInfo, ENVIRONMENT_DEFAULTS, type EnsureWalletResult, type EnvironmentDefaults, type FinalizeRecoveryInput, type FinalizeRecoveryResult, type KycNamespace, NotImplementedYetError, REACT_ADAPTER_VERSION, type ReconstructedSeed, type RecoveryNamespace, type RemoteWalletInfo, type RetryDeployResult, type SendXlmInput, type SendXlmResult, type SessionNamespace, type SettingsNamespace, type TxNamespace, type UnlockedSigningMaterial, type UseBalanceResult, type UseWalletActivityOptions, type UseWalletActivityResult, type UseWalletHistoryOptions, type UseWalletHistoryResult, type UseWalletStatusResult, type WalletActivityItem, type WalletNamespace, type WalletStatus, type WalletStatusValue, type WalletStreamActivityPayload, type WalletStreamBalancePayload, type WalletStreamEventType, type WalletStreamStatusPayload, type YieldNamespace, closeAllWalletSubscriptions, historyClearOptimistic, historyOptimisticPush, subscribeToWalletEvent, useAccesly, useBalance, useWalletActivity, useWalletHistory, useWalletStatus };

package/dist/index.d.ts

@@ -736,12 +736,21 @@ interface WalletStreamBalancePayload {
     readonly xlm: string;
 }
 /**
- * Activity emitida por el backend ya **filtrada y tipada** — solo eventos
- * relevantes para una wallet de Accesly (rotación de signers + transfers
- * IN/OUT de XLM). Otros eventos on-chain (debug, errores host, eventos
- * irrelevantes) se descartan en el server.
+ * Activity tipada lista para renderizar. Cuatro variants:
+ *
+ *  - `wallet-created`  — deploy inicial del Smart Account.
+ *  - `signer-rotated`  — rotación de signer (recovery).
+ *  - `transfer-in`     — recibió XLM.
+ *  - `transfer-out`    — envió XLM.
+ *
+ * Otros eventos on-chain (signer_added/removed internos, ruido) se descartan.
  */
 type WalletActivityItem = {
+    readonly type: 'wallet-created';
+    readonly txHash: string;
+    readonly ledger: number;
+    readonly timestamp: string | null;
+} | {
     readonly type: 'signer-rotated';
     readonly txHash: string;
     readonly ledger: number;
@@ -808,6 +817,77 @@ interface UseWalletActivityResult {
 }
 declare function useWalletActivity(walletAddress?: string | null, opts?: UseWalletActivityOptions): UseWalletActivityResult;
 
+/**
+ * Cliente y decoder de la **Stellar Expert public API** (indexer free, full
+ * retention, CORS abierto). Es la fuente primaria de `useWalletHistory`.
+ *
+ * Endpoints usados:
+ *   - GET /contract/{walletAddress}/events  — Smart Account events (rotaciones).
+ *   - GET /contract/{xlmSac}/events?topics=transfer
+ *         — Todos los transfers del SAC. Filtramos client-side por wallet.
+ *   - GET /contract/{walletAddress}          — Metadata del wallet (creación).
+ *
+ * Rate limit anonymous: ~1 req/s. Para zaramos cross-tab via BroadcastChannel
+ * en el hook que consume este módulo.
+ */
+
+type StellarExpertNetwork = 'testnet' | 'mainnet';
+
+/**
+ * `useWalletHistory(walletAddress?, opts?)` — historial completo de la wallet
+ * con Stellar Expert como indexer primario y opcional Soroban RPC autenticado
+ * para tail real-time.
+ *
+ * Características:
+ *  - 100% client-side, sin backend custom.
+ *  - Historia completa (mes+) gracias a la retention de Stellar Expert.
+ *  - Cache en `localStorage` per-wallet con TTL 12h → return instantáneo entre
+ *    page reloads y route changes.
+ *  - Polling cada 30s para nuevos events. Pausa si tab oculta.
+ *  - `BroadcastChannel` cross-tab para compartir SE rate limit — solo UN tab
+ *    hace fetch; los demás escuchan el resultado.
+ *  - Optimistic updates: el SDK puede llamar `historyOptimisticPush(addr, item)`
+ *    cuando acaba de mandar una tx exitosa para que aparezca inmediato sin
+ *    esperar el indexing de SE (~30-60s típico).
+ *  - Override de Soroban RPC: pasa `{ sorobanRpcUrl, sorobanRpcAuth }` para
+ *    que el tail (últimos eventos) venga via RPC con tu API key — sin lag.
+ */
+
+/**
+ * Inyecta un item de history "optimistically" — útil cuando acabás de hacer
+ * `tx.send` y querés que aparezca al instante sin esperar el indexing de SE.
+ * El item queda en memoria hasta que el próximo fetch del hook lo descarte
+ * (porque ya está en el feed real) o hasta `clearOptimistic(walletAddress)`.
+ *
+ * Usado internamente por `tx.send`; expuesto al integrador para casos custom.
+ */
+declare function historyOptimisticPush(walletAddress: string, item: WalletActivityItem): void;
+declare function historyClearOptimistic(walletAddress: string): void;
+interface UseWalletHistoryOptions {
+    /** `'testnet'` (default) o `'mainnet'`. */
+    readonly network?: StellarExpertNetwork;
+    /** Intervalo de poll para nuevos events (ms). Default 30s, 0 desactiva. */
+    readonly pollIntervalMs?: number;
+    /**
+     * Override del Soroban RPC para tail real-time. Si se provee, el hook usa
+     * tu RPC autenticado en vez de hacer poll a Stellar Expert para detectar
+     * nuevos events. Recomendado para producción.
+     */
+    readonly sorobanRpcUrl?: string;
+    readonly sorobanRpcAuth?: string;
+    /** Cantidad de transfers del XLM_SAC a scan-ear por fetch. Default 50. */
+    readonly transferScanLimit?: number;
+}
+interface UseWalletHistoryResult {
+    readonly events: readonly WalletActivityItem[];
+    readonly isLoading: boolean;
+    readonly error: Error | null;
+    readonly hasMore: boolean;
+    loadMore(): Promise<void>;
+    refresh(): Promise<void>;
+}
+declare function useWalletHistory(walletAddress?: string | null, opts?: UseWalletHistoryOptions): UseWalletHistoryResult;
+
 /**
  * @accesly/react — React Provider + `useAccesly` hook.
  *
@@ -832,4 +912,4 @@ declare function useWalletActivity(walletAddress?: string | null, opts?: UseWall
  */
 declare const REACT_ADAPTER_VERSION = "0.0.0";
 
-export { AcceslyContext, type AcceslyContextValue, type AcceslyHook, AcceslyProvider, type AcceslyProviderProps, type AuthNamespace, type BootstrapWalletInput, type CreateWalletInput, type CreatedWalletInfo, ENVIRONMENT_DEFAULTS, type EnsureWalletResult, type EnvironmentDefaults, type FinalizeRecoveryInput, type FinalizeRecoveryResult, type KycNamespace, NotImplementedYetError, REACT_ADAPTER_VERSION, type ReconstructedSeed, type RecoveryNamespace, type RemoteWalletInfo, type RetryDeployResult, type SendXlmInput, type SendXlmResult, type SessionNamespace, type SettingsNamespace, type TxNamespace, type UnlockedSigningMaterial, type UseBalanceResult, type UseWalletActivityOptions, type UseWalletActivityResult, type UseWalletStatusResult, type WalletActivityItem, type WalletNamespace, type WalletStatus, type WalletStatusValue, type WalletStreamActivityPayload, type WalletStreamBalancePayload, type WalletStreamEventType, type WalletStreamStatusPayload, type YieldNamespace, closeAllWalletSubscriptions, subscribeToWalletEvent, useAccesly, useBalance, useWalletActivity, useWalletStatus };
+export { AcceslyContext, type AcceslyContextValue, type AcceslyHook, AcceslyProvider, type AcceslyProviderProps, type AuthNamespace, type BootstrapWalletInput, type CreateWalletInput, type CreatedWalletInfo, ENVIRONMENT_DEFAULTS, type EnsureWalletResult, type EnvironmentDefaults, type FinalizeRecoveryInput, type FinalizeRecoveryResult, type KycNamespace, NotImplementedYetError, REACT_ADAPTER_VERSION, type ReconstructedSeed, type RecoveryNamespace, type RemoteWalletInfo, type RetryDeployResult, type SendXlmInput, type SendXlmResult, type SessionNamespace, type SettingsNamespace, type TxNamespace, type UnlockedSigningMaterial, type UseBalanceResult, type UseWalletActivityOptions, type UseWalletActivityResult, type UseWalletHistoryOptions, type UseWalletHistoryResult, type UseWalletStatusResult, type WalletActivityItem, type WalletNamespace, type WalletStatus, type WalletStatusValue, type WalletStreamActivityPayload, type WalletStreamBalancePayload, type WalletStreamEventType, type WalletStreamStatusPayload, type YieldNamespace, closeAllWalletSubscriptions, historyClearOptimistic, historyOptimisticPush, subscribeToWalletEvent, useAccesly, useBalance, useWalletActivity, useWalletHistory, useWalletStatus };