@unicitylabs/sphere-sdk 0.2.5 → 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,22 +173,6 @@ 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' | 'storage:remote-updated' | 'sync:started' | 'sync:completed' | 'sync:conflict' | 'sync:error';
 interface StorageEvent {
@@ -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;
 
@@ -1117,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";
@@ -1124,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";
@@ -1131,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;
@@ -1415,6 +1411,11 @@ interface NodeProvidersConfig {
     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;
@@ -1427,6 +1428,8 @@ interface NodeProviders {
     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

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,22 +173,6 @@ 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' | 'storage:remote-updated' | 'sync:started' | 'sync:completed' | 'sync:conflict' | 'sync:error';
 interface StorageEvent {
@@ -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;
 
@@ -1117,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";
@@ -1124,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";
@@ -1131,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;
@@ -1415,6 +1411,11 @@ interface NodeProvidersConfig {
     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;
@@ -1427,6 +1428,8 @@ interface NodeProviders {
     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

package/dist/impl/nodejs/index.js

@@ -27,7 +27,17 @@ var STORAGE_KEYS_GLOBAL = {
   /** Active addresses registry (JSON: TrackedAddressesStorage) */
   TRACKED_ADDRESSES: "tracked_addresses",
   /** Last processed Nostr wallet event timestamp (unix seconds), keyed per pubkey */
-  LAST_WALLET_EVENT_TS: "last_wallet_event_ts"
+  LAST_WALLET_EVENT_TS: "last_wallet_event_ts",
+  /** Group chat: joined groups */
+  GROUP_CHAT_GROUPS: "group_chat_groups",
+  /** Group chat: messages */
+  GROUP_CHAT_MESSAGES: "group_chat_messages",
+  /** Group chat: members */
+  GROUP_CHAT_MEMBERS: "group_chat_members",
+  /** Group chat: processed event IDs for deduplication */
+  GROUP_CHAT_PROCESSED_EVENTS: "group_chat_processed_events",
+  /** Group chat: last used relay URL (stale data detection) */
+  GROUP_CHAT_RELAY_URL: "group_chat_relay_url"
 };
 var STORAGE_KEYS_ADDRESS = {
   /** Pending transfers for this address */
@@ -108,27 +118,33 @@ var TEST_ELECTRUM_URL = "wss://fulcrum.alpha.testnet.unicity.network:50004";
 var TEST_NOSTR_RELAYS = [
   "wss://nostr-relay.testnet.unicity.network"
 ];
+var DEFAULT_GROUP_RELAYS = [
+  "wss://sphere-relay.unicity.network"
+];
 var NETWORKS = {
   mainnet: {
     name: "Mainnet",
     aggregatorUrl: DEFAULT_AGGREGATOR_URL,
     nostrRelays: DEFAULT_NOSTR_RELAYS,
     ipfsGateways: DEFAULT_IPFS_GATEWAYS,
-    electrumUrl: DEFAULT_ELECTRUM_URL
+    electrumUrl: DEFAULT_ELECTRUM_URL,
+    groupRelays: DEFAULT_GROUP_RELAYS
   },
   testnet: {
     name: "Testnet",
     aggregatorUrl: TEST_AGGREGATOR_URL,
     nostrRelays: TEST_NOSTR_RELAYS,
     ipfsGateways: DEFAULT_IPFS_GATEWAYS,
-    electrumUrl: TEST_ELECTRUM_URL
+    electrumUrl: TEST_ELECTRUM_URL,
+    groupRelays: DEFAULT_GROUP_RELAYS
   },
   dev: {
     name: "Development",
     aggregatorUrl: DEV_AGGREGATOR_URL,
     nostrRelays: TEST_NOSTR_RELAYS,
     ipfsGateways: DEFAULT_IPFS_GATEWAYS,
-    electrumUrl: TEST_ELECTRUM_URL
+    electrumUrl: TEST_ELECTRUM_URL,
+    groupRelays: DEFAULT_GROUP_RELAYS
   }
 };
 var TIMEOUTS = {
@@ -445,34 +461,6 @@ var FileTokenStorageProvider = class {
       return false;
     }
   }
-  async deleteToken(tokenId) {
-    const filePath = path2.join(this.tokensDir, `${tokenId}.json`);
-    if (fs2.existsSync(filePath)) {
-      fs2.unlinkSync(filePath);
-    }
-  }
-  async saveToken(tokenId, tokenData) {
-    fs2.writeFileSync(
-      path2.join(this.tokensDir, `${tokenId}.json`),
-      JSON.stringify(tokenData, null, 2)
-    );
-  }
-  async getToken(tokenId) {
-    const filePath = path2.join(this.tokensDir, `${tokenId}.json`);
-    if (!fs2.existsSync(filePath)) {
-      return null;
-    }
-    try {
-      const content = fs2.readFileSync(filePath, "utf-8");
-      return JSON.parse(content);
-    } catch {
-      return null;
-    }
-  }
-  async listTokenIds() {
-    const files = fs2.readdirSync(this.tokensDir).filter((f) => f.endsWith(".json") && f !== "_meta.json");
-    return files.map((f) => path2.basename(f, ".json"));
-  }
 };
 function createFileTokenStorageProvider(config) {
   return new FileTokenStorageProvider(config);
@@ -3617,9 +3605,13 @@ function mergeTxfData(local, remote) {
     remote._invalid ?? [],
     "tokenId"
   );
+  const localNametags = local._nametags ?? [];
+  const remoteNametags = remote._nametags ?? [];
+  const mergedNametags = mergeNametagsByName(localNametags, remoteNametags);
   const merged = {
     _meta: mergedMeta,
     _tombstones: mergedTombstones.length > 0 ? mergedTombstones : void 0,
+    _nametags: mergedNametags.length > 0 ? mergedNametags : void 0,
     _outbox: mergedOutbox.length > 0 ? mergedOutbox : void 0,
     _sent: mergedSent.length > 0 ? mergedSent : void 0,
     _invalid: mergedInvalid.length > 0 ? mergedInvalid : void 0,
@@ -3646,6 +3638,7 @@ function getTokenKeys(data) {
     "_sent",
     "_invalid",
     "_nametag",
+    "_nametags",
     "_mintOutbox",
     "_invalidatedNametags",
     "_integrity"
@@ -3653,7 +3646,7 @@ function getTokenKeys(data) {
   const keys = /* @__PURE__ */ new Set();
   for (const key of Object.keys(data)) {
     if (reservedKeys.has(key)) continue;
-    if (key.startsWith("archived-") || key.startsWith("_forked_") || key.startsWith("nametag-")) continue;
+    if (key.startsWith("archived-") || key.startsWith("_forked_")) continue;
     keys.add(key);
   }
   return keys;
@@ -3668,6 +3661,18 @@ function isTokenTombstoned(tokenId, localToken, remoteToken, tombstoneKeys) {
   void remoteToken;
   return false;
 }
+function mergeNametagsByName(local, remote) {
+  const seen = /* @__PURE__ */ new Map();
+  for (const item of local) {
+    if (item.name) seen.set(item.name, item);
+  }
+  for (const item of remote) {
+    if (item.name && !seen.has(item.name)) {
+      seen.set(item.name, item);
+    }
+  }
+  return Array.from(seen.values());
+}
 function mergeArrayById(local, remote, idField) {
   const seen = /* @__PURE__ */ new Map();
   for (const item of local) {
@@ -4022,14 +4027,11 @@ var AsyncSerialQueue = class {
 var WriteBuffer = class {
   /** Full TXF data from save() calls — latest wins */
   txfData = null;
-  /** Individual token mutations: key -> { op: 'save'|'delete', data? } */
-  tokenMutations = /* @__PURE__ */ new Map();
   get isEmpty() {
-    return this.txfData === null && this.tokenMutations.size === 0;
+    return this.txfData === null;
   }
   clear() {
     this.txfData = null;
-    this.tokenMutations.clear();
   }
   /**
    * Merge another buffer's contents into this one (for rollback).
@@ -4039,11 +4041,6 @@ var WriteBuffer = class {
     if (other.txfData && !this.txfData) {
       this.txfData = other.txfData;
     }
-    for (const [id, mutation] of other.tokenMutations) {
-      if (!this.tokenMutations.has(id)) {
-        this.tokenMutations.set(id, mutation);
-      }
-    }
   }
 };
 
@@ -4083,9 +4080,6 @@ var IpfsStorageProvider = class {
   subscriptionClient = null;
   /** Unsubscribe function from subscription client */
   subscriptionUnsubscribe = null;
-  /** In-memory buffer for individual token save/delete calls */
-  tokenBuffer = /* @__PURE__ */ new Map();
-  deletedTokenIds = /* @__PURE__ */ new Set();
   /** Write-behind buffer: serializes flush / sync / shutdown */
   flushQueue = new AsyncSerialQueue();
   /** Pending mutations not yet flushed to IPFS */
@@ -4274,14 +4268,6 @@ var IpfsStorageProvider = class {
         metaUpdate.lastCid = this.remoteCid;
       }
       const updatedData = { ...data, _meta: metaUpdate };
-      for (const [tokenId, tokenData] of this.tokenBuffer) {
-        if (!this.deletedTokenIds.has(tokenId)) {
-          updatedData[tokenId] = tokenData;
-        }
-      }
-      for (const tokenId of this.deletedTokenIds) {
-        delete updatedData[tokenId];
-      }
       const { cid } = await this.httpClient.upload(updatedData);
       this.log(`Content uploaded: CID=${cid}`);
       const baseSeq = this.ipnsSequenceNumber > this.lastKnownRemoteSequence ? this.ipnsSequenceNumber : this.lastKnownRemoteSequence;
@@ -4320,7 +4306,6 @@ var IpfsStorageProvider = class {
         lastCid: cid,
         version: this.dataVersion
       });
-      this.deletedTokenIds.clear();
       this.emitEvent({
         type: "storage:saved",
         timestamp: Date.now(),
@@ -4432,7 +4417,6 @@ var IpfsStorageProvider = class {
       if (typeof remoteVersion === "number" && remoteVersion > this.dataVersion) {
         this.dataVersion = remoteVersion;
       }
-      this.populateTokenBuffer(data);
       this.emitEvent({
         type: "storage:loaded",
         timestamp: Date.now(),
@@ -4478,7 +4462,7 @@ var IpfsStorageProvider = class {
           this.emitEvent({ type: "sync:completed", timestamp: Date.now() });
           return {
             success: saveResult2.success,
-            merged: this.enrichWithTokenBuffer(localData),
+            merged: localData,
             added: 0,
             removed: 0,
             conflicts: 0,
@@ -4493,7 +4477,7 @@ var IpfsStorageProvider = class {
           this.emitEvent({ type: "sync:completed", timestamp: Date.now() });
           return {
             success: true,
-            merged: this.enrichWithTokenBuffer(localData),
+            merged: localData,
             added: 0,
             removed: 0,
             conflicts: 0
@@ -4516,7 +4500,7 @@ var IpfsStorageProvider = class {
         });
         return {
           success: saveResult.success,
-          merged: this.enrichWithTokenBuffer(merged),
+          merged,
           added,
           removed,
           conflicts,
@@ -4542,21 +4526,6 @@ var IpfsStorageProvider = class {
   // ---------------------------------------------------------------------------
   // Private Helpers
   // ---------------------------------------------------------------------------
-  /**
-   * Enrich TXF data with individually-buffered tokens before returning to caller.
-   * PaymentsModule.createStorageData() passes empty tokens (they're stored via
-   * saveToken()), but loadFromStorageData() needs them in the merged result.
-   */
-  enrichWithTokenBuffer(data) {
-    if (this.tokenBuffer.size === 0) return data;
-    const enriched = { ...data };
-    for (const [tokenId, tokenData] of this.tokenBuffer) {
-      if (!this.deletedTokenIds.has(tokenId)) {
-        enriched[tokenId] = tokenData;
-      }
-    }
-    return enriched;
-  }
   // ---------------------------------------------------------------------------
   // Optional Methods
   // ---------------------------------------------------------------------------
@@ -4586,8 +4555,6 @@ var IpfsStorageProvider = class {
     const result = await this._doSave(emptyData);
     if (result.success) {
       this.cache.clear();
-      this.tokenBuffer.clear();
-      this.deletedTokenIds.clear();
       await this.statePersistence.clear(this.ipnsName);
     }
     return result.success;
@@ -4598,27 +4565,6 @@ var IpfsStorageProvider = class {
       this.eventCallbacks.delete(callback);
     };
   }
-  async saveToken(tokenId, tokenData) {
-    this.pendingBuffer.tokenMutations.set(tokenId, { op: "save", data: tokenData });
-    this.tokenBuffer.set(tokenId, tokenData);
-    this.deletedTokenIds.delete(tokenId);
-    this.scheduleFlush();
-  }
-  async getToken(tokenId) {
-    if (this.deletedTokenIds.has(tokenId)) return null;
-    return this.tokenBuffer.get(tokenId) ?? null;
-  }
-  async listTokenIds() {
-    return Array.from(this.tokenBuffer.keys()).filter(
-      (id) => !this.deletedTokenIds.has(id)
-    );
-  }
-  async deleteToken(tokenId) {
-    this.pendingBuffer.tokenMutations.set(tokenId, { op: "delete" });
-    this.tokenBuffer.delete(tokenId);
-    this.deletedTokenIds.add(tokenId);
-    this.scheduleFlush();
-  }
   // ---------------------------------------------------------------------------
   // Public Accessors
   // ---------------------------------------------------------------------------
@@ -4710,26 +4656,6 @@ var IpfsStorageProvider = class {
       console.log(`[IPFS-Storage] ${message}`);
     }
   }
-  META_KEYS = /* @__PURE__ */ new Set([
-    "_meta",
-    "_tombstones",
-    "_outbox",
-    "_sent",
-    "_invalid",
-    "_nametag",
-    "_mintOutbox",
-    "_invalidatedNametags",
-    "_integrity"
-  ]);
-  populateTokenBuffer(data) {
-    this.tokenBuffer.clear();
-    this.deletedTokenIds.clear();
-    for (const key of Object.keys(data)) {
-      if (!this.META_KEYS.has(key)) {
-        this.tokenBuffer.set(key, data[key]);
-      }
-    }
-  }
 };
 
 // impl/nodejs/ipfs/nodejs-ipfs-state-persistence.ts
@@ -4955,6 +4881,20 @@ function resolvePriceConfig(config) {
     debug: config.debug
   };
 }
+function resolveGroupChatConfig(network, config) {
+  if (!config) return void 0;
+  if (config === true) {
+    const netConfig2 = getNetworkConfig(network);
+    return { relays: [...netConfig2.groupRelays] };
+  }
+  if (typeof config === "object" && config.enabled === false) {
+    return void 0;
+  }
+  const netConfig = getNetworkConfig(network);
+  return {
+    relays: config.relays ?? [...netConfig.groupRelays]
+  };
+}
 
 // impl/nodejs/index.ts
 function createNodeProviders(config) {
@@ -4968,8 +4908,10 @@ function createNodeProviders(config) {
   });
   const ipfsSync = config?.tokenSync?.ipfs;
   const ipfsTokenStorage = ipfsSync?.enabled ? createNodeIpfsStorageProvider(ipfsSync.config, storage) : void 0;
+  const groupChat = resolveGroupChatConfig(network, config?.groupChat);
   return {
     storage,
+    groupChat,
     tokenStorage: createFileTokenStorageProvider({
       tokensDir: config?.tokensDir ?? "./sphere-tokens"
     }),