@unicitylabs/sphere-sdk 0.2.3 → 0.3.0

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

@@ -3,6 +3,19 @@ import { AggregatorClient } from '@unicitylabs/state-transition-sdk/lib/api/Aggr
 import { RootTrustBase } from '@unicitylabs/state-transition-sdk/lib/bft/RootTrustBase';
 import { TransferCommitment as TransferCommitment$1 } from '@unicitylabs/state-transition-sdk/lib/transaction/TransferCommitment';
 
+interface GroupChatModuleConfig {
+    /** Override relay URLs (default: from network config) */
+    relays?: string[];
+    /** Default message fetch limit (default: 50) */
+    defaultMessageLimit?: number;
+    /** Max previous message IDs in ordering tags (default: 3) */
+    maxPreviousTags?: number;
+    /** Reconnect delay in ms (default: 3000) */
+    reconnectDelayMs?: number;
+    /** Max reconnect attempts (default: 5) */
+    maxReconnectAttempts?: number;
+}
+
 /**
  * SDK2 Core Types
  * Platform-independent type definitions
@@ -160,24 +173,8 @@ interface TokenStorageProvider<TData = unknown> extends BaseProvider {
      * Subscribe to storage events
      */
     onEvent?(callback: StorageEventCallback): () => void;
-    /**
-     * Save individual token (for file-based storage like lottery pattern)
-     */
-    saveToken?(tokenId: string, tokenData: unknown): Promise<void>;
-    /**
-     * Get individual token
-     */
-    getToken?(tokenId: string): Promise<unknown | null>;
-    /**
-     * List all token IDs
-     */
-    listTokenIds?(): Promise<string[]>;
-    /**
-     * Delete individual token
-     */
-    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;
@@ -301,10 +298,6 @@ declare class FileTokenStorageProvider implements TokenStorageProvider<TxfStorag
     save(data: TxfStorageDataBase): Promise<SaveResult>;
     sync(localData: TxfStorageDataBase): Promise<SyncResult<TxfStorageDataBase>>;
     clear(): Promise<boolean>;
-    deleteToken(tokenId: string): Promise<void>;
-    saveToken(tokenId: string, tokenData: unknown): Promise<void>;
-    getToken(tokenId: string): Promise<unknown | null>;
-    listTokenIds(): Promise<string[]>;
 }
 declare function createFileTokenStorageProvider(config: FileTokenStorageConfig | string): FileTokenStorageProvider;
 
@@ -470,6 +463,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 +533,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 +718,7 @@ declare class NostrTransportProvider implements TransportProvider {
     private status;
     private nostrClient;
     private mainSubscriptionId;
+    private processedEventIds;
     private messageHandlers;
     private transferHandlers;
     private paymentRequestHandlers;
@@ -830,6 +830,7 @@ declare class NostrTransportProvider implements TransportProvider {
     private createEvent;
     private createEncryptedEvent;
     private publishEvent;
+    fetchPendingEvents(): Promise<void>;
     private queryEvents;
     private walletSubscriptionId;
     private chatSubscriptionId;
@@ -1109,6 +1110,7 @@ declare const NETWORKS: {
         readonly nostrRelays: readonly ["wss://relay.unicity.network", "wss://relay.damus.io", "wss://nos.lol", "wss://relay.nostr.band"];
         readonly ipfsGateways: readonly ["https://ipfs.unicity.network", "https://dweb.link", "https://ipfs.io"];
         readonly electrumUrl: "wss://fulcrum.alpha.unicity.network:50004";
+        readonly groupRelays: readonly ["wss://sphere-relay.unicity.network"];
     };
     readonly testnet: {
         readonly name: "Testnet";
@@ -1116,6 +1118,7 @@ declare const NETWORKS: {
         readonly nostrRelays: readonly ["wss://nostr-relay.testnet.unicity.network"];
         readonly ipfsGateways: readonly ["https://ipfs.unicity.network", "https://dweb.link", "https://ipfs.io"];
         readonly electrumUrl: "wss://fulcrum.alpha.testnet.unicity.network:50004";
+        readonly groupRelays: readonly ["wss://sphere-relay.unicity.network"];
     };
     readonly dev: {
         readonly name: "Development";
@@ -1123,6 +1126,7 @@ declare const NETWORKS: {
         readonly nostrRelays: readonly ["wss://nostr-relay.testnet.unicity.network"];
         readonly ipfsGateways: readonly ["https://ipfs.unicity.network", "https://dweb.link", "https://ipfs.io"];
         readonly electrumUrl: "wss://fulcrum.alpha.testnet.unicity.network:50004";
+        readonly groupRelays: readonly ["wss://sphere-relay.unicity.network"];
     };
 };
 type NetworkType = keyof typeof NETWORKS;
@@ -1322,6 +1326,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 +1382,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 +1409,13 @@ interface NodeProvidersConfig {
     l1?: NodeL1Config;
     /** Price provider configuration (optional — enables fiat value display) */
     price?: BasePriceConfig;
+    /** Token sync backends configuration */
+    tokenSync?: NodeTokenSyncConfig;
+    /** Group chat (NIP-29) configuration. true = enable with defaults, object = custom config */
+    groupChat?: {
+        enabled?: boolean;
+        relays?: string[];
+    } | boolean;
 }
 interface NodeProviders {
     storage: StorageProvider;
@@ -1367,6 +1426,10 @@ 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>;
+    /** Group chat config (resolved, for passing to Sphere.init) */
+    groupChat?: GroupChatModuleConfig | boolean;
 }
 /**
  * Create all Node.js providers with default configuration
@@ -1406,4 +1469,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

@@ -3,6 +3,19 @@ import { AggregatorClient } from '@unicitylabs/state-transition-sdk/lib/api/Aggr
 import { RootTrustBase } from '@unicitylabs/state-transition-sdk/lib/bft/RootTrustBase';
 import { TransferCommitment as TransferCommitment$1 } from '@unicitylabs/state-transition-sdk/lib/transaction/TransferCommitment';
 
+interface GroupChatModuleConfig {
+    /** Override relay URLs (default: from network config) */
+    relays?: string[];
+    /** Default message fetch limit (default: 50) */
+    defaultMessageLimit?: number;
+    /** Max previous message IDs in ordering tags (default: 3) */
+    maxPreviousTags?: number;
+    /** Reconnect delay in ms (default: 3000) */
+    reconnectDelayMs?: number;
+    /** Max reconnect attempts (default: 5) */
+    maxReconnectAttempts?: number;
+}
+
 /**
  * SDK2 Core Types
  * Platform-independent type definitions
@@ -160,24 +173,8 @@ interface TokenStorageProvider<TData = unknown> extends BaseProvider {
      * Subscribe to storage events
      */
     onEvent?(callback: StorageEventCallback): () => void;
-    /**
-     * Save individual token (for file-based storage like lottery pattern)
-     */
-    saveToken?(tokenId: string, tokenData: unknown): Promise<void>;
-    /**
-     * Get individual token
-     */
-    getToken?(tokenId: string): Promise<unknown | null>;
-    /**
-     * List all token IDs
-     */
-    listTokenIds?(): Promise<string[]>;
-    /**
-     * Delete individual token
-     */
-    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;
@@ -301,10 +298,6 @@ declare class FileTokenStorageProvider implements TokenStorageProvider<TxfStorag
     save(data: TxfStorageDataBase): Promise<SaveResult>;
     sync(localData: TxfStorageDataBase): Promise<SyncResult<TxfStorageDataBase>>;
     clear(): Promise<boolean>;
-    deleteToken(tokenId: string): Promise<void>;
-    saveToken(tokenId: string, tokenData: unknown): Promise<void>;
-    getToken(tokenId: string): Promise<unknown | null>;
-    listTokenIds(): Promise<string[]>;
 }
 declare function createFileTokenStorageProvider(config: FileTokenStorageConfig | string): FileTokenStorageProvider;
 
@@ -470,6 +463,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 +533,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 +718,7 @@ declare class NostrTransportProvider implements TransportProvider {
     private status;
     private nostrClient;
     private mainSubscriptionId;
+    private processedEventIds;
     private messageHandlers;
     private transferHandlers;
     private paymentRequestHandlers;
@@ -830,6 +830,7 @@ declare class NostrTransportProvider implements TransportProvider {
     private createEvent;
     private createEncryptedEvent;
     private publishEvent;
+    fetchPendingEvents(): Promise<void>;
     private queryEvents;
     private walletSubscriptionId;
     private chatSubscriptionId;
@@ -1109,6 +1110,7 @@ declare const NETWORKS: {
         readonly nostrRelays: readonly ["wss://relay.unicity.network", "wss://relay.damus.io", "wss://nos.lol", "wss://relay.nostr.band"];
         readonly ipfsGateways: readonly ["https://ipfs.unicity.network", "https://dweb.link", "https://ipfs.io"];
         readonly electrumUrl: "wss://fulcrum.alpha.unicity.network:50004";
+        readonly groupRelays: readonly ["wss://sphere-relay.unicity.network"];
     };
     readonly testnet: {
         readonly name: "Testnet";
@@ -1116,6 +1118,7 @@ declare const NETWORKS: {
         readonly nostrRelays: readonly ["wss://nostr-relay.testnet.unicity.network"];
         readonly ipfsGateways: readonly ["https://ipfs.unicity.network", "https://dweb.link", "https://ipfs.io"];
         readonly electrumUrl: "wss://fulcrum.alpha.testnet.unicity.network:50004";
+        readonly groupRelays: readonly ["wss://sphere-relay.unicity.network"];
     };
     readonly dev: {
         readonly name: "Development";
@@ -1123,6 +1126,7 @@ declare const NETWORKS: {
         readonly nostrRelays: readonly ["wss://nostr-relay.testnet.unicity.network"];
         readonly ipfsGateways: readonly ["https://ipfs.unicity.network", "https://dweb.link", "https://ipfs.io"];
         readonly electrumUrl: "wss://fulcrum.alpha.testnet.unicity.network:50004";
+        readonly groupRelays: readonly ["wss://sphere-relay.unicity.network"];
     };
 };
 type NetworkType = keyof typeof NETWORKS;
@@ -1322,6 +1326,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 +1382,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 +1409,13 @@ interface NodeProvidersConfig {
     l1?: NodeL1Config;
     /** Price provider configuration (optional — enables fiat value display) */
     price?: BasePriceConfig;
+    /** Token sync backends configuration */
+    tokenSync?: NodeTokenSyncConfig;
+    /** Group chat (NIP-29) configuration. true = enable with defaults, object = custom config */
+    groupChat?: {
+        enabled?: boolean;
+        relays?: string[];
+    } | boolean;
 }
 interface NodeProviders {
     storage: StorageProvider;
@@ -1367,6 +1426,10 @@ 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>;
+    /** Group chat config (resolved, for passing to Sphere.init) */
+    groupChat?: GroupChatModuleConfig | boolean;
 }
 /**
  * Create all Node.js providers with default configuration
@@ -1406,4 +1469,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 };