@unicitylabs/sphere-sdk 0.2.2 → 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;
@@ -552,6 +558,8 @@ interface IncomingPaymentRequest {
     id: string;
     /** Transport-specific pubkey of sender */
     senderTransportPubkey: string;
+    /** Sender's nametag (if included in encrypted content) */
+    senderNametag?: string;
     /** Parsed request data */
     request: {
         requestId: string;
@@ -675,6 +683,14 @@ type UUIDGenerator = () => string;
  * WebSocket is injected via factory for cross-platform support
  */
 
+/**
+ * Minimal key-value storage interface for transport persistence.
+ * Used to persist the last processed event timestamp across sessions.
+ */
+interface TransportStorageAdapter {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string): Promise<void>;
+}
 interface NostrTransportProviderConfig {
     /** Nostr relay URLs */
     relays?: string[];
@@ -692,6 +708,8 @@ interface NostrTransportProviderConfig {
     createWebSocket: WebSocketFactory;
     /** UUID generator (optional, defaults to crypto.randomUUID) */
     generateUUID?: UUIDGenerator;
+    /** Optional storage adapter for persisting subscription timestamps */
+    storage?: TransportStorageAdapter;
 }
 declare class NostrTransportProvider implements TransportProvider {
     readonly id = "nostr";
@@ -699,11 +717,15 @@ declare class NostrTransportProvider implements TransportProvider {
     readonly type: "p2p";
     readonly description = "P2P messaging via Nostr protocol";
     private config;
+    private storage;
+    /** In-memory max event timestamp to avoid read-before-write races in updateLastEventTimestamp. */
+    private lastEventTs;
     private identity;
     private keyManager;
     private status;
     private nostrClient;
     private mainSubscriptionId;
+    private processedEventIds;
     private messageHandlers;
     private transferHandlers;
     private paymentRequestHandlers;
@@ -800,6 +822,12 @@ declare class NostrTransportProvider implements TransportProvider {
     publishBroadcast(content: string, tags?: string[]): Promise<string>;
     onEvent(callback: TransportEventCallback): () => void;
     private handleEvent;
+    /**
+     * Save the max event timestamp to storage (fire-and-forget, no await needed by caller).
+     * Uses in-memory `lastEventTs` to avoid read-before-write race conditions
+     * when multiple events arrive in quick succession.
+     */
+    private updateLastEventTimestamp;
     private handleDirectMessage;
     private handleGiftWrap;
     private handleTokenTransfer;
@@ -809,6 +837,7 @@ declare class NostrTransportProvider implements TransportProvider {
     private createEvent;
     private createEncryptedEvent;
     private publishEvent;
+    fetchPendingEvents(): Promise<void>;
     private queryEvents;
     private walletSubscriptionId;
     private chatSubscriptionId;
@@ -1301,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
@@ -1321,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;
@@ -1336,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;
@@ -1346,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
@@ -1385,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;
@@ -552,6 +558,8 @@ interface IncomingPaymentRequest {
     id: string;
     /** Transport-specific pubkey of sender */
     senderTransportPubkey: string;
+    /** Sender's nametag (if included in encrypted content) */
+    senderNametag?: string;
     /** Parsed request data */
     request: {
         requestId: string;
@@ -675,6 +683,14 @@ type UUIDGenerator = () => string;
  * WebSocket is injected via factory for cross-platform support
  */
 
+/**
+ * Minimal key-value storage interface for transport persistence.
+ * Used to persist the last processed event timestamp across sessions.
+ */
+interface TransportStorageAdapter {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string): Promise<void>;
+}
 interface NostrTransportProviderConfig {
     /** Nostr relay URLs */
     relays?: string[];
@@ -692,6 +708,8 @@ interface NostrTransportProviderConfig {
     createWebSocket: WebSocketFactory;
     /** UUID generator (optional, defaults to crypto.randomUUID) */
     generateUUID?: UUIDGenerator;
+    /** Optional storage adapter for persisting subscription timestamps */
+    storage?: TransportStorageAdapter;
 }
 declare class NostrTransportProvider implements TransportProvider {
     readonly id = "nostr";
@@ -699,11 +717,15 @@ declare class NostrTransportProvider implements TransportProvider {
     readonly type: "p2p";
     readonly description = "P2P messaging via Nostr protocol";
     private config;
+    private storage;
+    /** In-memory max event timestamp to avoid read-before-write races in updateLastEventTimestamp. */
+    private lastEventTs;
     private identity;
     private keyManager;
     private status;
     private nostrClient;
     private mainSubscriptionId;
+    private processedEventIds;
     private messageHandlers;
     private transferHandlers;
     private paymentRequestHandlers;
@@ -800,6 +822,12 @@ declare class NostrTransportProvider implements TransportProvider {
     publishBroadcast(content: string, tags?: string[]): Promise<string>;
     onEvent(callback: TransportEventCallback): () => void;
     private handleEvent;
+    /**
+     * Save the max event timestamp to storage (fire-and-forget, no await needed by caller).
+     * Uses in-memory `lastEventTs` to avoid read-before-write race conditions
+     * when multiple events arrive in quick succession.
+     */
+    private updateLastEventTimestamp;
     private handleDirectMessage;
     private handleGiftWrap;
     private handleTokenTransfer;
@@ -809,6 +837,7 @@ declare class NostrTransportProvider implements TransportProvider {
     private createEvent;
     private createEncryptedEvent;
     private publishEvent;
+    fetchPendingEvents(): Promise<void>;
     private queryEvents;
     private walletSubscriptionId;
     private chatSubscriptionId;
@@ -1301,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
@@ -1321,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;
@@ -1336,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;
@@ -1346,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
@@ -1385,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 };