@accesly/react 1.2.0 → 1.3.1

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { Environment, CognitoConfig, AuthClient, SessionStorage, DeviceStore, TelemetrySink, TokenManager, AccesslyEndpoints, AuthStatus, CredentialRecord, EncryptedEnvelope } from '@accesly/core';
+import { Environment, CognitoConfig, AuthClient, SessionStorage, DeviceStore, TelemetrySink, TokenManager, AccesslyEndpoints, AuthStatus, CredentialRecord, EncryptedEnvelope, WalletHistoryItem } from '@accesly/core';
 import * as react from 'react';
 import { ReactNode } from 'react';
 
@@ -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,52 @@ interface UseWalletActivityResult {
 }
 declare function useWalletActivity(walletAddress?: string | null, opts?: UseWalletActivityOptions): UseWalletActivityResult;
 
+/**
+ * `useWalletHistory(walletAddress?, opts?)` — historial completo de la wallet
+ * pre-decodificado desde Stellar Expert (indexer free, full retention).
+ *
+ * El backend de Accesly **proxea** las requests a Stellar Expert porque SE
+ * bloquea CORS desde browsers (Cloudflare retorna 403 en cross-origin). El
+ * proxy hace el call server-side, decodea topics + amounts, y devuelve items
+ * tipados listos para renderizar.
+ *
+ * Features:
+ *  - Cache en `localStorage` per-wallet con TTL 12h → render instantáneo en
+ *    reloads + navegación.
+ *  - Polling cada 30s para nuevos events. Pausa si tab oculta.
+ *  - `BroadcastChannel` cross-tab para compartir fetches — solo UN tab hace
+ *    el request, los demás escuchan el resultado vía canal.
+ *  - Optimistic updates: el SDK inserta el item al instante cuando `tx.send`
+ *    confirma, sin esperar el indexing de SE (~30-60s típico).
+ */
+
+/**
+ * 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 hasta que el próximo fetch confirma que ya está en el feed.
+ */
+declare function historyOptimisticPush(walletAddress: string, item: WalletHistoryItem | WalletActivityItem): void;
+declare function historyClearOptimistic(walletAddress: string): void;
+interface UseWalletHistoryOptions {
+    /** Intervalo de poll para nuevos events (ms). Default 30s, 0 desactiva. */
+    readonly pollIntervalMs?: number;
+    /**
+     * Cuántos transfers del XLM_SAC scan-ear por fetch. Default 50, max 500
+     * (5 paginated calls). En testnet hay millones de transfers globalmente; si
+     * tu wallet tiene pocos transfers, sube este número para encontrarlos.
+     */
+    readonly transferScanLimit?: number;
+}
+interface UseWalletHistoryResult {
+    readonly events: readonly WalletHistoryItem[];
+    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 +887,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

@@ -1,4 +1,4 @@
-import { Environment, CognitoConfig, AuthClient, SessionStorage, DeviceStore, TelemetrySink, TokenManager, AccesslyEndpoints, AuthStatus, CredentialRecord, EncryptedEnvelope } from '@accesly/core';
+import { Environment, CognitoConfig, AuthClient, SessionStorage, DeviceStore, TelemetrySink, TokenManager, AccesslyEndpoints, AuthStatus, CredentialRecord, EncryptedEnvelope, WalletHistoryItem } from '@accesly/core';
 import * as react from 'react';
 import { ReactNode } from 'react';
 
@@ -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,52 @@ interface UseWalletActivityResult {
 }
 declare function useWalletActivity(walletAddress?: string | null, opts?: UseWalletActivityOptions): UseWalletActivityResult;
 
+/**
+ * `useWalletHistory(walletAddress?, opts?)` — historial completo de la wallet
+ * pre-decodificado desde Stellar Expert (indexer free, full retention).
+ *
+ * El backend de Accesly **proxea** las requests a Stellar Expert porque SE
+ * bloquea CORS desde browsers (Cloudflare retorna 403 en cross-origin). El
+ * proxy hace el call server-side, decodea topics + amounts, y devuelve items
+ * tipados listos para renderizar.
+ *
+ * Features:
+ *  - Cache en `localStorage` per-wallet con TTL 12h → render instantáneo en
+ *    reloads + navegación.
+ *  - Polling cada 30s para nuevos events. Pausa si tab oculta.
+ *  - `BroadcastChannel` cross-tab para compartir fetches — solo UN tab hace
+ *    el request, los demás escuchan el resultado vía canal.
+ *  - Optimistic updates: el SDK inserta el item al instante cuando `tx.send`
+ *    confirma, sin esperar el indexing de SE (~30-60s típico).
+ */
+
+/**
+ * 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 hasta que el próximo fetch confirma que ya está en el feed.
+ */
+declare function historyOptimisticPush(walletAddress: string, item: WalletHistoryItem | WalletActivityItem): void;
+declare function historyClearOptimistic(walletAddress: string): void;
+interface UseWalletHistoryOptions {
+    /** Intervalo de poll para nuevos events (ms). Default 30s, 0 desactiva. */
+    readonly pollIntervalMs?: number;
+    /**
+     * Cuántos transfers del XLM_SAC scan-ear por fetch. Default 50, max 500
+     * (5 paginated calls). En testnet hay millones de transfers globalmente; si
+     * tu wallet tiene pocos transfers, sube este número para encontrarlos.
+     */
+    readonly transferScanLimit?: number;
+}
+interface UseWalletHistoryResult {
+    readonly events: readonly WalletHistoryItem[];
+    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 +887,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 };