@unicitylabs/sphere-sdk 0.2.3 → 0.2.5

package/dist/impl/nodejs/index.d.cts

@@ -177,7 +177,7 @@ interface TokenStorageProvider<TData = unknown> extends BaseProvider {
      */
     deleteToken?(tokenId: string): Promise<void>;
 }
-type StorageEventType = 'storage:saving' | 'storage:saved' | 'storage:loading' | 'storage:loaded' | 'storage:error' | 'sync:started' | 'sync:completed' | 'sync:conflict' | 'sync:error';
+type StorageEventType = 'storage:saving' | 'storage:saved' | 'storage:loading' | 'storage:loaded' | 'storage:error' | 'storage:remote-updated' | 'sync:started' | 'sync:completed' | 'sync:conflict' | 'sync:error';
 interface StorageEvent {
     type: StorageEventType;
     timestamp: number;
@@ -470,6 +470,12 @@ interface TransportProvider extends BaseProvider {
      * @returns Unsubscribe function
      */
     onInstantSplitReceived?(handler: InstantSplitBundleHandler): () => void;
+    /**
+     * Fetch pending events from transport (one-shot query).
+     * Creates a temporary subscription, processes events through normal handlers,
+     * and resolves after EOSE (End Of Stored Events).
+     */
+    fetchPendingEvents?(): Promise<void>;
 }
 /**
  * Payload for sending instant split bundles
@@ -534,7 +540,7 @@ interface IncomingTokenTransfer {
     payload: TokenTransferPayload;
     timestamp: number;
 }
-type TokenTransferHandler = (transfer: IncomingTokenTransfer) => void;
+type TokenTransferHandler = (transfer: IncomingTokenTransfer) => void | Promise<void>;
 interface PaymentRequestPayload {
     /** Amount requested (in smallest units) */
     amount: string | bigint;
@@ -719,6 +725,7 @@ declare class NostrTransportProvider implements TransportProvider {
     private status;
     private nostrClient;
     private mainSubscriptionId;
+    private processedEventIds;
     private messageHandlers;
     private transferHandlers;
     private paymentRequestHandlers;
@@ -830,6 +837,7 @@ declare class NostrTransportProvider implements TransportProvider {
     private createEvent;
     private createEncryptedEvent;
     private publishEvent;
+    fetchPendingEvents(): Promise<void>;
     private queryEvents;
     private walletSubscriptionId;
     private chatSubscriptionId;
@@ -1322,6 +1330,42 @@ interface BaseProviders {
     price?: PriceProvider;
 }
 
+/** IPFS storage provider configuration */
+interface IpfsStorageConfig {
+    /** Gateway URLs for HTTP API (defaults to Unicity dedicated nodes) */
+    gateways?: string[];
+    /** Content fetch timeout in ms (default: 15000) */
+    fetchTimeoutMs?: number;
+    /** IPNS resolution timeout in ms (default: 10000) */
+    resolveTimeoutMs?: number;
+    /** IPNS publish timeout in ms (default: 30000) */
+    publishTimeoutMs?: number;
+    /** Gateway connectivity test timeout in ms (default: 5000) */
+    connectivityTimeoutMs?: number;
+    /** IPNS record lifetime in ms (default: 99 years) */
+    ipnsLifetimeMs?: number;
+    /** IPNS cache TTL in ms (default: 60000) */
+    ipnsCacheTtlMs?: number;
+    /** Circuit breaker failure threshold (default: 3) */
+    circuitBreakerThreshold?: number;
+    /** Circuit breaker cooldown in ms (default: 60000) */
+    circuitBreakerCooldownMs?: number;
+    /** Known-fresh window in ms (default: 30000) */
+    knownFreshWindowMs?: number;
+    /** Enable debug logging (default: false) */
+    debug?: boolean;
+    /** WebSocket factory for IPNS push subscriptions (cross-platform) */
+    createWebSocket?: WebSocketFactory;
+    /** Override WebSocket URL (auto-derived from gateways if omitted) */
+    wsUrl?: string;
+    /** Fallback polling interval in ms when WS unavailable (default: 90000) */
+    fallbackPollIntervalMs?: number;
+    /** Debounce for push-triggered sync in ms (default: 500) */
+    syncDebounceMs?: number;
+    /** Debounce interval for background flush in ms (default: 2000) */
+    flushDebounceMs?: number;
+}
+
 /**
  * Node.js Implementation
  * Providers for CLI/Node.js usage
@@ -1342,6 +1386,18 @@ type NodeOracleConfig = BaseOracleConfig & NodeOracleExtensions;
  * Same as base
  */
 type NodeL1Config = L1Config;
+/** Node.js IPFS sync configuration */
+interface NodeIpfsSyncConfig {
+    /** Enable IPFS sync (default: false) */
+    enabled?: boolean;
+    /** IPFS storage provider configuration */
+    config?: IpfsStorageConfig;
+}
+/** Node.js token sync configuration */
+interface NodeTokenSyncConfig {
+    /** IPFS sync backend */
+    ipfs?: NodeIpfsSyncConfig;
+}
 interface NodeProvidersConfig {
     /** Network preset: mainnet, testnet, or dev */
     network?: NetworkType;
@@ -1357,6 +1413,8 @@ interface NodeProvidersConfig {
     l1?: NodeL1Config;
     /** Price provider configuration (optional — enables fiat value display) */
     price?: BasePriceConfig;
+    /** Token sync backends configuration */
+    tokenSync?: NodeTokenSyncConfig;
 }
 interface NodeProviders {
     storage: StorageProvider;
@@ -1367,6 +1425,8 @@ interface NodeProviders {
     l1?: L1Config;
     /** Price provider (optional — enables fiat value display) */
     price?: PriceProvider;
+    /** IPFS token storage provider (when tokenSync.ipfs.enabled is true) */
+    ipfsTokenStorage?: TokenStorageProvider<TxfStorageDataBase>;
 }
 /**
  * Create all Node.js providers with default configuration
@@ -1406,4 +1466,4 @@ interface NodeProviders {
  */
 declare function createNodeProviders(config?: NodeProvidersConfig): NodeProviders;
 
-export { type BaseOracleConfig, type BaseProviders, type BaseTransportConfig, FileStorageProvider, type FileStorageProviderConfig, type FileTokenStorageConfig, FileTokenStorageProvider, type IWebSocket, type L1Config, type NodeL1Config, type NodeOracleConfig, type NodeProviders, type NodeProvidersConfig, type NodeTransportConfig, NodeTrustBaseLoader, NostrTransportProvider, type NostrTransportProviderConfig, type TrustBaseLoader$1 as TrustBaseLoader, UnicityAggregatorProvider, type UnicityAggregatorProviderConfig, UnicityOracleProvider, type UnicityOracleProviderConfig, type WebSocketFactory, createFileStorageProvider, createFileTokenStorageProvider, createNodeProviders, createNodeTrustBaseLoader, createNodeWebSocketFactory, createNostrTransportProvider, createUnicityAggregatorProvider, createUnicityOracleProvider };
+export { type BaseOracleConfig, type BaseProviders, type BaseTransportConfig, FileStorageProvider, type FileStorageProviderConfig, type FileTokenStorageConfig, FileTokenStorageProvider, type IWebSocket, type L1Config, type NodeIpfsSyncConfig, type NodeL1Config, type NodeOracleConfig, type NodeProviders, type NodeProvidersConfig, type NodeTokenSyncConfig, type NodeTransportConfig, NodeTrustBaseLoader, NostrTransportProvider, type NostrTransportProviderConfig, type TrustBaseLoader$1 as TrustBaseLoader, UnicityAggregatorProvider, type UnicityAggregatorProviderConfig, UnicityOracleProvider, type UnicityOracleProviderConfig, type WebSocketFactory, createFileStorageProvider, createFileTokenStorageProvider, createNodeProviders, createNodeTrustBaseLoader, createNodeWebSocketFactory, createNostrTransportProvider, createUnicityAggregatorProvider, createUnicityOracleProvider };

package/dist/impl/nodejs/index.d.ts

@@ -177,7 +177,7 @@ interface TokenStorageProvider<TData = unknown> extends BaseProvider {
      */
     deleteToken?(tokenId: string): Promise<void>;
 }
-type StorageEventType = 'storage:saving' | 'storage:saved' | 'storage:loading' | 'storage:loaded' | 'storage:error' | 'sync:started' | 'sync:completed' | 'sync:conflict' | 'sync:error';
+type StorageEventType = 'storage:saving' | 'storage:saved' | 'storage:loading' | 'storage:loaded' | 'storage:error' | 'storage:remote-updated' | 'sync:started' | 'sync:completed' | 'sync:conflict' | 'sync:error';
 interface StorageEvent {
     type: StorageEventType;
     timestamp: number;
@@ -470,6 +470,12 @@ interface TransportProvider extends BaseProvider {
      * @returns Unsubscribe function
      */
     onInstantSplitReceived?(handler: InstantSplitBundleHandler): () => void;
+    /**
+     * Fetch pending events from transport (one-shot query).
+     * Creates a temporary subscription, processes events through normal handlers,
+     * and resolves after EOSE (End Of Stored Events).
+     */
+    fetchPendingEvents?(): Promise<void>;
 }
 /**
  * Payload for sending instant split bundles
@@ -534,7 +540,7 @@ interface IncomingTokenTransfer {
     payload: TokenTransferPayload;
     timestamp: number;
 }
-type TokenTransferHandler = (transfer: IncomingTokenTransfer) => void;
+type TokenTransferHandler = (transfer: IncomingTokenTransfer) => void | Promise<void>;
 interface PaymentRequestPayload {
     /** Amount requested (in smallest units) */
     amount: string | bigint;
@@ -719,6 +725,7 @@ declare class NostrTransportProvider implements TransportProvider {
     private status;
     private nostrClient;
     private mainSubscriptionId;
+    private processedEventIds;
     private messageHandlers;
     private transferHandlers;
     private paymentRequestHandlers;
@@ -830,6 +837,7 @@ declare class NostrTransportProvider implements TransportProvider {
     private createEvent;
     private createEncryptedEvent;
     private publishEvent;
+    fetchPendingEvents(): Promise<void>;
     private queryEvents;
     private walletSubscriptionId;
     private chatSubscriptionId;
@@ -1322,6 +1330,42 @@ interface BaseProviders {
     price?: PriceProvider;
 }
 
+/** IPFS storage provider configuration */
+interface IpfsStorageConfig {
+    /** Gateway URLs for HTTP API (defaults to Unicity dedicated nodes) */
+    gateways?: string[];
+    /** Content fetch timeout in ms (default: 15000) */
+    fetchTimeoutMs?: number;
+    /** IPNS resolution timeout in ms (default: 10000) */
+    resolveTimeoutMs?: number;
+    /** IPNS publish timeout in ms (default: 30000) */
+    publishTimeoutMs?: number;
+    /** Gateway connectivity test timeout in ms (default: 5000) */
+    connectivityTimeoutMs?: number;
+    /** IPNS record lifetime in ms (default: 99 years) */
+    ipnsLifetimeMs?: number;
+    /** IPNS cache TTL in ms (default: 60000) */
+    ipnsCacheTtlMs?: number;
+    /** Circuit breaker failure threshold (default: 3) */
+    circuitBreakerThreshold?: number;
+    /** Circuit breaker cooldown in ms (default: 60000) */
+    circuitBreakerCooldownMs?: number;
+    /** Known-fresh window in ms (default: 30000) */
+    knownFreshWindowMs?: number;
+    /** Enable debug logging (default: false) */
+    debug?: boolean;
+    /** WebSocket factory for IPNS push subscriptions (cross-platform) */
+    createWebSocket?: WebSocketFactory;
+    /** Override WebSocket URL (auto-derived from gateways if omitted) */
+    wsUrl?: string;
+    /** Fallback polling interval in ms when WS unavailable (default: 90000) */
+    fallbackPollIntervalMs?: number;
+    /** Debounce for push-triggered sync in ms (default: 500) */
+    syncDebounceMs?: number;
+    /** Debounce interval for background flush in ms (default: 2000) */
+    flushDebounceMs?: number;
+}
+
 /**
  * Node.js Implementation
  * Providers for CLI/Node.js usage
@@ -1342,6 +1386,18 @@ type NodeOracleConfig = BaseOracleConfig & NodeOracleExtensions;
  * Same as base
  */
 type NodeL1Config = L1Config;
+/** Node.js IPFS sync configuration */
+interface NodeIpfsSyncConfig {
+    /** Enable IPFS sync (default: false) */
+    enabled?: boolean;
+    /** IPFS storage provider configuration */
+    config?: IpfsStorageConfig;
+}
+/** Node.js token sync configuration */
+interface NodeTokenSyncConfig {
+    /** IPFS sync backend */
+    ipfs?: NodeIpfsSyncConfig;
+}
 interface NodeProvidersConfig {
     /** Network preset: mainnet, testnet, or dev */
     network?: NetworkType;
@@ -1357,6 +1413,8 @@ interface NodeProvidersConfig {
     l1?: NodeL1Config;
     /** Price provider configuration (optional — enables fiat value display) */
     price?: BasePriceConfig;
+    /** Token sync backends configuration */
+    tokenSync?: NodeTokenSyncConfig;
 }
 interface NodeProviders {
     storage: StorageProvider;
@@ -1367,6 +1425,8 @@ interface NodeProviders {
     l1?: L1Config;
     /** Price provider (optional — enables fiat value display) */
     price?: PriceProvider;
+    /** IPFS token storage provider (when tokenSync.ipfs.enabled is true) */
+    ipfsTokenStorage?: TokenStorageProvider<TxfStorageDataBase>;
 }
 /**
  * Create all Node.js providers with default configuration
@@ -1406,4 +1466,4 @@ interface NodeProviders {
  */
 declare function createNodeProviders(config?: NodeProvidersConfig): NodeProviders;
 
-export { type BaseOracleConfig, type BaseProviders, type BaseTransportConfig, FileStorageProvider, type FileStorageProviderConfig, type FileTokenStorageConfig, FileTokenStorageProvider, type IWebSocket, type L1Config, type NodeL1Config, type NodeOracleConfig, type NodeProviders, type NodeProvidersConfig, type NodeTransportConfig, NodeTrustBaseLoader, NostrTransportProvider, type NostrTransportProviderConfig, type TrustBaseLoader$1 as TrustBaseLoader, UnicityAggregatorProvider, type UnicityAggregatorProviderConfig, UnicityOracleProvider, type UnicityOracleProviderConfig, type WebSocketFactory, createFileStorageProvider, createFileTokenStorageProvider, createNodeProviders, createNodeTrustBaseLoader, createNodeWebSocketFactory, createNostrTransportProvider, createUnicityAggregatorProvider, createUnicityOracleProvider };
+export { type BaseOracleConfig, type BaseProviders, type BaseTransportConfig, FileStorageProvider, type FileStorageProviderConfig, type FileTokenStorageConfig, FileTokenStorageProvider, type IWebSocket, type L1Config, type NodeIpfsSyncConfig, type NodeL1Config, type NodeOracleConfig, type NodeProviders, type NodeProvidersConfig, type NodeTokenSyncConfig, type NodeTransportConfig, NodeTrustBaseLoader, NostrTransportProvider, type NostrTransportProviderConfig, type TrustBaseLoader$1 as TrustBaseLoader, UnicityAggregatorProvider, type UnicityAggregatorProviderConfig, UnicityOracleProvider, type UnicityOracleProviderConfig, type WebSocketFactory, createFileStorageProvider, createFileTokenStorageProvider, createNodeProviders, createNodeTrustBaseLoader, createNodeWebSocketFactory, createNostrTransportProvider, createUnicityAggregatorProvider, createUnicityOracleProvider };