@unicitylabs/sphere-sdk 0.2.5 → 0.3.0

package/dist/core/index.d.cts

@@ -1,6 +1,73 @@
 import { Token as Token$1 } from '@unicitylabs/state-transition-sdk/lib/token/Token';
 import elliptic from 'elliptic';
 
+/**
+ * Group Chat Types (NIP-29)
+ * Plain interfaces for SDK consumers — no classes, no UI helpers.
+ */
+declare const GroupRole: {
+    readonly ADMIN: "ADMIN";
+    readonly MODERATOR: "MODERATOR";
+    readonly MEMBER: "MEMBER";
+};
+type GroupRole = (typeof GroupRole)[keyof typeof GroupRole];
+declare const GroupVisibility: {
+    readonly PUBLIC: "PUBLIC";
+    readonly PRIVATE: "PRIVATE";
+};
+type GroupVisibility = (typeof GroupVisibility)[keyof typeof GroupVisibility];
+interface GroupData {
+    id: string;
+    relayUrl: string;
+    name: string;
+    description?: string;
+    picture?: string;
+    visibility: GroupVisibility;
+    createdAt: number;
+    updatedAt?: number;
+    memberCount?: number;
+    unreadCount?: number;
+    lastMessageTime?: number;
+    lastMessageText?: string;
+    /** When the current user joined this group locally (used to filter old events) */
+    localJoinedAt?: number;
+}
+interface GroupMessageData {
+    id?: string;
+    groupId: string;
+    content: string;
+    timestamp: number;
+    senderPubkey: string;
+    senderNametag?: string;
+    replyToId?: string;
+    previousIds?: string[];
+}
+interface GroupMemberData {
+    pubkey: string;
+    groupId: string;
+    role: GroupRole;
+    nametag?: string;
+    joinedAt: number;
+}
+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;
+}
+interface CreateGroupOptions {
+    name: string;
+    description?: string;
+    picture?: string;
+    visibility?: GroupVisibility;
+}
+
 /**
  * Cryptographic utilities for SDK2
  *
@@ -618,7 +685,7 @@ interface TrackedAddress extends TrackedAddressEntry {
     /** Primary nametag (from nametag cache, without @ prefix) */
     readonly nametag?: string;
 }
-type SphereEventType = 'transfer:incoming' | 'transfer:confirmed' | 'transfer:failed' | 'payment_request:incoming' | 'payment_request:accepted' | 'payment_request:rejected' | 'payment_request:paid' | 'payment_request:response' | 'message:dm' | 'message:broadcast' | 'sync:started' | 'sync:completed' | 'sync:provider' | 'sync:error' | 'connection:changed' | 'nametag:registered' | 'nametag:recovered' | 'identity:changed' | 'address:activated' | 'address:hidden' | 'address:unhidden' | 'sync:remote-update';
+type SphereEventType = 'transfer:incoming' | 'transfer:confirmed' | 'transfer:failed' | 'payment_request:incoming' | 'payment_request:accepted' | 'payment_request:rejected' | 'payment_request:paid' | 'payment_request:response' | 'message:dm' | 'message:broadcast' | 'sync:started' | 'sync:completed' | 'sync:provider' | 'sync:error' | 'connection:changed' | 'nametag:registered' | 'nametag:recovered' | 'identity:changed' | 'address:activated' | 'address:hidden' | 'address:unhidden' | 'sync:remote-update' | 'groupchat:message' | 'groupchat:joined' | 'groupchat:left' | 'groupchat:kicked' | 'groupchat:group_deleted' | 'groupchat:updated' | 'groupchat:connection';
 interface SphereEventMap {
     'transfer:incoming': IncomingTransfer;
     'transfer:confirmed': TransferResult;
@@ -685,6 +752,26 @@ interface SphereEventMap {
         added: number;
         removed: number;
     };
+    'groupchat:message': GroupMessageData;
+    'groupchat:joined': {
+        groupId: string;
+        groupName: string;
+    };
+    'groupchat:left': {
+        groupId: string;
+    };
+    'groupchat:kicked': {
+        groupId: string;
+        groupName: string;
+    };
+    'groupchat:group_deleted': {
+        groupId: string;
+        groupName: string;
+    };
+    'groupchat:updated': Record<string, never>;
+    'groupchat:connection': {
+        connected: boolean;
+    };
 }
 type SphereEventHandler<T extends SphereEventType> = (data: SphereEventMap[T]) => void;
 /**
@@ -1326,22 +1413,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 {
@@ -1667,7 +1738,7 @@ declare class PaymentsModule {
     private archivedTokens;
     private forkedTokens;
     private transactionHistory;
-    private nametag;
+    private nametags;
     private paymentRequests;
     private paymentRequestHandlers;
     private outgoingPaymentRequests;
@@ -2025,17 +2096,6 @@ declare class PaymentsModule {
      * @returns `true` if the token was added, `false` if rejected as duplicate or tombstoned.
      */
     addToken(token: Token, skipHistory?: boolean): Promise<boolean>;
-    /**
-     * Save token as individual file to token storage providers
-     * Similar to lottery's saveReceivedToken() pattern
-     */
-    private saveTokenToFileStorage;
-    /**
-     * Load tokens from file storage providers (lottery compatibility)
-     * This loads tokens from file-based storage that may have been saved
-     * by other applications using the same storage directory.
-     */
-    private loadTokensFromFileStorage;
     /**
      * Update an existing token or add it if not found.
      *
@@ -2057,11 +2117,6 @@ declare class PaymentsModule {
      * @param skipHistory - When `true`, skip creating a transaction history entry (default `false`).
      */
     removeToken(tokenId: string, recipientNametag?: string, skipHistory?: boolean): Promise<void>;
-    /**
-     * Delete physical token file(s) from all storage providers.
-     * Finds files by matching the SDK token ID prefix in the filename.
-     */
-    private deleteTokenFiles;
     /**
      * Get all tombstone entries.
      *
@@ -2189,11 +2244,17 @@ declare class PaymentsModule {
      */
     setNametag(nametag: NametagData): Promise<void>;
     /**
-     * Get the current nametag data.
+     * Get the current (first) nametag data.
      *
      * @returns The nametag data, or `null` if no nametag is set.
      */
     getNametag(): NametagData | null;
+    /**
+     * Get all nametag data entries.
+     *
+     * @returns A copy of the nametags array.
+     */
+    getNametags(): NametagData[];
     /**
      * Check whether a nametag is currently set.
      *
@@ -2201,19 +2262,9 @@ declare class PaymentsModule {
      */
     hasNametag(): boolean;
     /**
-     * Remove the current nametag data from memory and storage.
+     * Remove all nametag data from memory and storage.
      */
     clearNametag(): Promise<void>;
-    /**
-     * Save nametag to file storage for lottery compatibility
-     * Creates file: nametag-{name}.json
-     */
-    private saveNametagToFileStorage;
-    /**
-     * Load nametag from file storage (lottery compatibility)
-     * Looks for file: nametag-{name}.json
-     */
-    private loadNametagFromFileStorage;
     /**
      * Mint a nametag token on-chain (like Sphere wallet and lottery)
      * This creates the nametag token required for receiving tokens via PROXY addresses
@@ -2446,6 +2497,126 @@ declare class CommunicationsModule {
     private ensureInitialized;
 }
 
+/**
+ * Group Chat Module (NIP-29)
+ *
+ * Relay-based group chat using NIP-29 protocol on a dedicated Nostr relay.
+ * Embeds its own NostrClient — does NOT share the wallet's TransportProvider.
+ */
+
+interface GroupChatModuleDependencies {
+    identity: FullIdentity;
+    storage: StorageProvider;
+    emitEvent: <T extends SphereEventType>(type: T, data: SphereEventMap[T]) => void;
+}
+declare class GroupChatModule {
+    private config;
+    private deps;
+    private client;
+    private keyManager;
+    private connected;
+    private connecting;
+    private connectPromise;
+    private reconnectAttempts;
+    private reconnectTimer;
+    private subscriptionIds;
+    private groups;
+    private messages;
+    private members;
+    private processedEventIds;
+    private pendingLeaves;
+    private persistTimer;
+    private persistPromise;
+    private relayAdminPubkeys;
+    private relayAdminFetchPromise;
+    private messageHandlers;
+    constructor(config?: GroupChatModuleConfig);
+    initialize(deps: GroupChatModuleDependencies): void;
+    load(): Promise<void>;
+    destroy(): void;
+    private destroyConnection;
+    connect(): Promise<void>;
+    getConnectionStatus(): boolean;
+    private doConnect;
+    private scheduleReconnect;
+    private subscribeToJoinedGroups;
+    private subscribeToGroup;
+    private handleGroupEvent;
+    private handleMetadataEvent;
+    private handleModerationEvent;
+    private updateMembersFromEvent;
+    private updateAdminsFromEvent;
+    private restoreJoinedGroups;
+    fetchAvailableGroups(): Promise<GroupData[]>;
+    joinGroup(groupId: string, inviteCode?: string): Promise<boolean>;
+    leaveGroup(groupId: string): Promise<boolean>;
+    createGroup(options: CreateGroupOptions): Promise<GroupData | null>;
+    deleteGroup(groupId: string): Promise<boolean>;
+    createInvite(groupId: string): Promise<string | null>;
+    sendMessage(groupId: string, content: string, replyToId?: string): Promise<GroupMessageData | null>;
+    fetchMessages(groupId: string, since?: number, limit?: number): Promise<GroupMessageData[]>;
+    getGroups(): GroupData[];
+    getGroup(groupId: string): GroupData | null;
+    getMessages(groupId: string): GroupMessageData[];
+    getMembers(groupId: string): GroupMemberData[];
+    getMember(groupId: string, pubkey: string): GroupMemberData | null;
+    getTotalUnreadCount(): number;
+    markGroupAsRead(groupId: string): void;
+    kickUser(groupId: string, userPubkey: string, reason?: string): Promise<boolean>;
+    deleteMessage(groupId: string, messageId: string): Promise<boolean>;
+    isCurrentUserAdmin(groupId: string): boolean;
+    isCurrentUserModerator(groupId: string): boolean;
+    /**
+     * Check if current user can moderate a group:
+     * - Group admin/moderator can always moderate their group
+     * - Relay admins can moderate public groups
+     */
+    canModerateGroup(groupId: string): Promise<boolean>;
+    isCurrentUserRelayAdmin(): Promise<boolean>;
+    getCurrentUserRole(groupId: string): GroupRole | null;
+    onMessage(handler: (message: GroupMessageData) => void): () => void;
+    getRelayUrls(): string[];
+    getMyPublicKey(): string | null;
+    private fetchRelayAdmins;
+    private doFetchRelayAdmins;
+    private fetchGroupMetadataInternal;
+    private fetchAndSaveMembers;
+    private fetchGroupMembersInternal;
+    private fetchGroupAdminsInternal;
+    private saveMessageToMemory;
+    private deleteMessageFromMemory;
+    private saveMemberToMemory;
+    private removeMemberFromMemory;
+    private removeGroupFromMemory;
+    private updateGroupLastMessage;
+    private updateMemberNametag;
+    private addProcessedEventId;
+    /** Schedule a debounced persist (coalesces rapid event bursts). */
+    private schedulePersist;
+    /** Persist immediately (for explicit flush points). */
+    private persistAll;
+    private doPersistAll;
+    private persistGroups;
+    private persistMessages;
+    private persistMembers;
+    private persistProcessedEvents;
+    private checkAndClearOnRelayChange;
+    private wrapMessageContent;
+    private unwrapMessageContent;
+    private getGroupIdFromEvent;
+    private getGroupIdFromMetadataEvent;
+    private extractReplyTo;
+    private extractPreviousIds;
+    private parseGroupMetadata;
+    /** Subscribe and track the subscription ID for cleanup. */
+    private trackSubscription;
+    /** Subscribe for a one-shot fetch, auto-unsubscribe on EOSE or timeout. */
+    private oneshotSubscription;
+    private ensureInitialized;
+    private ensureConnected;
+    private randomId;
+}
+
 /** Network configurations */
 declare const NETWORKS: {
     readonly mainnet: {
@@ -2454,6 +2625,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";
@@ -2461,6 +2633,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";
@@ -2468,6 +2641,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;
@@ -2581,6 +2755,8 @@ interface SphereCreateOptions {
      * Use createBrowserProviders({ network: 'testnet' }) to set up testnet providers.
      */
     network?: NetworkType;
+    /** Group chat configuration (NIP-29). Omit to disable groupchat. */
+    groupChat?: GroupChatModuleConfig | boolean;
 }
 /** Options for loading existing wallet */
 interface SphereLoadOptions {
@@ -2602,6 +2778,8 @@ interface SphereLoadOptions {
      * Use createBrowserProviders({ network: 'testnet' }) to set up testnet providers.
      */
     network?: NetworkType;
+    /** Group chat configuration (NIP-29). Omit to disable groupchat. */
+    groupChat?: GroupChatModuleConfig | boolean;
 }
 /** Options for importing a wallet */
 interface SphereImportOptions {
@@ -2631,6 +2809,8 @@ interface SphereImportOptions {
     l1?: L1Config;
     /** Optional price provider for fiat conversion */
     price?: PriceProvider;
+    /** Group chat configuration (NIP-29). Omit to disable groupchat. */
+    groupChat?: GroupChatModuleConfig | boolean;
 }
 /** L1 (ALPHA blockchain) configuration */
 interface L1Config {
@@ -2669,6 +2849,13 @@ interface SphereInitOptions {
      * Use createBrowserProviders({ network: 'testnet' }) to set up testnet providers.
      */
     network?: NetworkType;
+    /**
+     * Group chat configuration (NIP-29).
+     * - `true`: Enable with network-default relays
+     * - `GroupChatModuleConfig`: Enable with custom config
+     * - Omit/undefined: No groupchat module
+     */
+    groupChat?: GroupChatModuleConfig | boolean;
 }
 /** Result of init operation */
 interface SphereInitResult {
@@ -2704,6 +2891,7 @@ declare class Sphere {
     private _priceProvider;
     private _payments;
     private _communications;
+    private _groupChat;
     private eventHandlers;
     private constructor();
     /**
@@ -2736,6 +2924,18 @@ declare class Sphere {
      * ```
      */
     static init(options: SphereInitOptions): Promise<SphereInitResult>;
+    /**
+     * Resolve groupChat config from init/create/load options.
+     * - `true` → use network-default relays
+     * - `GroupChatModuleConfig` → pass through
+     * - `undefined` → no groupchat
+     */
+    /**
+     * Resolve GroupChat config from Sphere.init() options.
+     * Note: impl/shared/resolvers.ts has a similar resolver for provider-level config
+     * (different input shape: { enabled?, relays? }). Both fill relay URLs from network defaults.
+     */
+    private static resolveGroupChatConfig;
     /**
      * Create new wallet with mnemonic
      */
@@ -2792,6 +2992,8 @@ declare class Sphere {
     get payments(): PaymentsModule;
     /** Communications module */
     get communications(): CommunicationsModule;
+    /** Group chat module (NIP-29). Null if not configured. */
+    get groupChat(): GroupChatModule | null;
     /** Current identity (public info only) */
     get identity(): Identity | null;
     /** Is ready */