@unicitylabs/sphere-sdk 0.1.3 → 0.1.4

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

@@ -21,11 +21,12 @@ interface BaseProvider extends ProviderMetadata {
     getStatus(): ProviderStatus;
 }
 interface Identity {
-    readonly publicKey: string;
+    /** 33-byte compressed secp256k1 public key (for L3 chain) */
+    readonly chainPubkey: string;
     /** L1 address (alpha1...) */
-    readonly address: string;
-    /** L3 predicate address (DIRECT://...) */
-    readonly predicateAddress?: string;
+    readonly l1Address: string;
+    /** L3 DIRECT address (DIRECT://...) */
+    readonly directAddress?: string;
     readonly ipnsName?: string;
     readonly nametag?: string;
 }
@@ -288,9 +289,10 @@ interface TransportProvider extends BaseProvider {
     setIdentity(identity: FullIdentity): void;
     /**
      * Send encrypted direct message
+     * @param recipientTransportPubkey - Transport-specific pubkey for messaging
      * @returns Event ID
      */
-    sendMessage(recipientPubkey: string, content: string): Promise<string>;
+    sendMessage(recipientTransportPubkey: string, content: string): Promise<string>;
     /**
      * Subscribe to incoming direct messages
      * @returns Unsubscribe function
@@ -298,9 +300,10 @@ interface TransportProvider extends BaseProvider {
     onMessage(handler: MessageHandler): () => void;
     /**
      * Send token transfer payload
+     * @param recipientTransportPubkey - Transport-specific pubkey for messaging
      * @returns Event ID
      */
-    sendTokenTransfer(recipientPubkey: string, payload: TokenTransferPayload): Promise<string>;
+    sendTokenTransfer(recipientTransportPubkey: string, payload: TokenTransferPayload): Promise<string>;
     /**
      * Subscribe to incoming token transfers
      * @returns Unsubscribe function
@@ -310,11 +313,25 @@ interface TransportProvider extends BaseProvider {
      * Resolve nametag to public key
      */
     resolveNametag?(nametag: string): Promise<string | null>;
+    /**
+     * Resolve nametag to full address information
+     * Returns transportPubkey, chainPubkey, l1Address, directAddress, proxyAddress
+     */
+    resolveNametagInfo?(nametag: string): Promise<NametagInfo | null>;
+    /**
+     * Recover nametag for current identity by decrypting stored encrypted nametag
+     * Used after wallet import to recover associated nametag
+     * @returns Decrypted nametag or null if none found
+     */
+    recoverNametag?(): Promise<string | null>;
     /**
      * Register a nametag for this identity
+     * @param nametag - Nametag to register
+     * @param chainPubkey - 33-byte compressed secp256k1 public key (for L1/L3)
+     * @param directAddress - L3 DIRECT address (DIRECT://...)
      * @returns true if successful, false if already taken
      */
-    registerNametag?(nametag: string, publicKey: string): Promise<boolean>;
+    registerNametag?(nametag: string, chainPubkey: string, directAddress: string): Promise<boolean>;
     /**
      * Publish nametag binding
      */
@@ -329,9 +346,10 @@ interface TransportProvider extends BaseProvider {
     publishBroadcast?(content: string, tags?: string[]): Promise<string>;
     /**
      * Send payment request to a recipient
+     * @param recipientTransportPubkey - Transport-specific pubkey for messaging
      * @returns Event ID
      */
-    sendPaymentRequest?(recipientPubkey: string, request: PaymentRequestPayload): Promise<string>;
+    sendPaymentRequest?(recipientTransportPubkey: string, request: PaymentRequestPayload): Promise<string>;
     /**
      * Subscribe to incoming payment requests
      * @returns Unsubscribe function
@@ -339,9 +357,10 @@ interface TransportProvider extends BaseProvider {
     onPaymentRequest?(handler: PaymentRequestHandler): () => void;
     /**
      * Send response to a payment request
+     * @param recipientTransportPubkey - Transport-specific pubkey for messaging
      * @returns Event ID
      */
-    sendPaymentRequestResponse?(recipientPubkey: string, response: PaymentRequestResponsePayload): Promise<string>;
+    sendPaymentRequestResponse?(recipientTransportPubkey: string, response: PaymentRequestResponsePayload): Promise<string>;
     /**
      * Subscribe to incoming payment request responses
      * @returns Unsubscribe function
@@ -376,7 +395,10 @@ interface TransportProvider extends BaseProvider {
 }
 interface IncomingMessage {
     id: string;
-    senderPubkey: string;
+    /** Transport-specific pubkey of sender */
+    senderTransportPubkey: string;
+    /** Sender's nametag (if known from NIP-17 unwrap) */
+    senderNametag?: string;
     content: string;
     timestamp: number;
     encrypted: boolean;
@@ -391,13 +413,15 @@ interface TokenTransferPayload {
     memo?: string;
     /** Sender info */
     sender?: {
-        pubkey: string;
+        /** Transport-specific pubkey */
+        transportPubkey: string;
         nametag?: string;
     };
 }
 interface IncomingTokenTransfer {
     id: string;
-    senderPubkey: string;
+    /** Transport-specific pubkey of sender */
+    senderTransportPubkey: string;
     payload: TokenTransferPayload;
     timestamp: number;
 }
@@ -417,8 +441,8 @@ interface PaymentRequestPayload {
 interface IncomingPaymentRequest {
     /** Event ID */
     id: string;
-    /** Sender's public key */
-    senderPubkey: string;
+    /** Transport-specific pubkey of sender */
+    senderTransportPubkey: string;
     /** Parsed request data */
     request: {
         requestId: string;
@@ -446,8 +470,8 @@ interface PaymentRequestResponsePayload {
 interface IncomingPaymentRequestResponse {
     /** Event ID */
     id: string;
-    /** Responder's public key */
-    responderPubkey: string;
+    /** Transport-specific pubkey of responder */
+    responderTransportPubkey: string;
     /** Parsed response data */
     response: {
         requestId: string;
@@ -461,7 +485,8 @@ interface IncomingPaymentRequestResponse {
 type PaymentRequestResponseHandler = (response: IncomingPaymentRequestResponse) => void;
 interface IncomingBroadcast {
     id: string;
-    authorPubkey: string;
+    /** Transport-specific pubkey of author */
+    authorTransportPubkey: string;
     content: string;
     tags: string[];
     timestamp: number;
@@ -475,6 +500,26 @@ interface TransportEvent {
     error?: string;
 }
 type TransportEventCallback = (event: TransportEvent) => void;
+/**
+ * Full nametag address information
+ * Used for resolving nametag to all address formats
+ */
+interface NametagInfo {
+    /** Nametag name (without @) */
+    nametag: string;
+    /** Transport-specific pubkey (for messaging/encryption) */
+    transportPubkey: string;
+    /** 33-byte compressed secp256k1 public key (for L3 chain) */
+    chainPubkey: string;
+    /** L1 address (alpha1...) */
+    l1Address: string;
+    /** L3 DIRECT address (DIRECT://...) */
+    directAddress: string;
+    /** L3 PROXY address derived from nametag hash (PROXY:...) */
+    proxyAddress: string;
+    /** Event timestamp */
+    timestamp: number;
+}
 
 /**
  * WebSocket Abstraction
@@ -515,6 +560,7 @@ type UUIDGenerator = () => string;
  * - Real secp256k1 event signing
  * - NIP-04 encryption/decryption
  * - Event ID calculation
+ * - NostrClient for reliable connection management (ping, reconnect, NIP-42)
  *
  * WebSocket is injected via factory for cross-platform support
  */
@@ -546,15 +592,14 @@ declare class NostrTransportProvider implements TransportProvider {
     private identity;
     private keyManager;
     private status;
-    private connections;
-    private reconnectAttempts;
+    private nostrClient;
+    private mainSubscriptionId;
     private messageHandlers;
     private transferHandlers;
     private paymentRequestHandlers;
     private paymentRequestResponseHandlers;
     private broadcastHandlers;
     private eventCallbacks;
-    private subscriptions;
     constructor(config: NostrTransportProviderConfig);
     connect(): Promise<void>;
     disconnect(): Promise<void>;
@@ -576,6 +621,8 @@ declare class NostrTransportProvider implements TransportProvider {
     /**
      * Remove a relay dynamically
      * Will disconnect from the relay if connected
+     * NOTE: NostrClient doesn't support removing individual relays at runtime.
+     * We remove from config so it won't be used on next connect().
      */
     removeRelay(relayUrl: string): Promise<boolean>;
     /**
@@ -601,16 +648,22 @@ declare class NostrTransportProvider implements TransportProvider {
     sendPaymentRequestResponse(recipientPubkey: string, payload: PaymentRequestResponsePayload): Promise<string>;
     onPaymentRequestResponse(handler: PaymentRequestResponseHandler): () => void;
     resolveNametag(nametag: string): Promise<string | null>;
+    resolveNametagInfo(nametag: string): Promise<NametagInfo | null>;
+    /**
+     * Recover nametag for the current identity by searching for encrypted nametag events
+     * Used after wallet import to recover associated nametag
+     * @returns Decrypted nametag or null if none found
+     */
+    recoverNametag(): Promise<string | null>;
     publishNametag(nametag: string, address: string): Promise<void>;
-    registerNametag(nametag: string, _publicKey: string): Promise<boolean>;
+    registerNametag(nametag: string, _publicKey: string, directAddress?: string): Promise<boolean>;
+    private broadcastSubscriptions;
     subscribeToBroadcast(tags: string[], handler: BroadcastHandler): () => void;
     publishBroadcast(content: string, tags?: string[]): Promise<string>;
     onEvent(callback: TransportEventCallback): () => void;
-    private connectToRelay;
-    private scheduleReconnect;
-    private handleRelayMessage;
     private handleEvent;
     private handleDirectMessage;
+    private handleGiftWrap;
     private handleTokenTransfer;
     private handlePaymentRequest;
     private handlePaymentRequestResponse;
@@ -619,8 +672,8 @@ declare class NostrTransportProvider implements TransportProvider {
     private createEncryptedEvent;
     private publishEvent;
     private queryEvents;
-    private queryEventsFromRelay;
-    private unsubscribeFromRelay;
+    private walletSubscriptionId;
+    private chatSubscriptionId;
     private subscribeToEvents;
     private subscribeToTags;
     private decryptContent;
@@ -787,7 +840,7 @@ type OracleEventCallback = (event: OracleEvent) => void;
  * Browser: fetch from URL
  * Node.js: read from file
  */
-interface TrustBaseLoader {
+interface TrustBaseLoader$1 {
     /**
      * Load trust base JSON data
      * @returns Trust base data or null if not available
@@ -825,7 +878,7 @@ interface UnicityAggregatorProviderConfig {
     /** Enable debug logging */
     debug?: boolean;
     /** Trust base loader (platform-specific) */
-    trustBaseLoader?: TrustBaseLoader;
+    trustBaseLoader?: TrustBaseLoader$1;
 }
 /**
  * Unicity Aggregator Provider
@@ -888,32 +941,6 @@ declare const UnicityOracleProvider: typeof UnicityAggregatorProvider;
 /** @deprecated Use UnicityAggregatorProviderConfig instead */
 type UnicityOracleProviderConfig = UnicityAggregatorProviderConfig;
 
-/**
- * Node.js Oracle Exports
- * Re-exports shared oracle with Node.js-specific TrustBaseLoader
- */
-
-/**
- * Node.js TrustBase loader using fs
- */
-declare class NodeTrustBaseLoader implements TrustBaseLoader {
-    private filePath;
-    constructor(filePath?: string);
-    load(): Promise<unknown | null>;
-}
-/**
- * Create Node.js TrustBase loader
- */
-declare function createNodeTrustBaseLoader(filePath?: string): TrustBaseLoader;
-/**
- * Create UnicityAggregatorProvider with Node.js TrustBase loader
- */
-declare function createUnicityAggregatorProvider(config: Omit<UnicityAggregatorProviderConfig, 'trustBaseLoader'> & {
-    trustBasePath?: string;
-}): UnicityAggregatorProvider;
-/** @deprecated Use createUnicityAggregatorProvider instead */
-declare const createUnicityOracleProvider: typeof createUnicityAggregatorProvider;
-
 /** Network configurations */
 declare const NETWORKS: {
     readonly mainnet: {
@@ -940,6 +967,55 @@ declare const NETWORKS: {
 };
 type NetworkType = keyof typeof NETWORKS;
 
+/**
+ * Shared TrustBase Loader Logic
+ * Common embedded trustbase data and base loader
+ */
+
+interface TrustBaseLoader {
+    load(): Promise<unknown | null>;
+}
+/**
+ * Base TrustBase loader with embedded fallback
+ */
+declare abstract class BaseTrustBaseLoader implements TrustBaseLoader {
+    protected network: NetworkType;
+    constructor(network?: NetworkType);
+    /**
+     * Try to load from external source (file, URL, etc.)
+     * Override in subclass
+     */
+    protected abstract loadFromExternal(): Promise<unknown | null>;
+    load(): Promise<unknown | null>;
+}
+
+/**
+ * Node.js Oracle Exports
+ * Re-exports shared oracle with Node.js-specific TrustBaseLoader
+ */
+
+/**
+ * Node.js TrustBase loader - loads from file or uses embedded data
+ */
+declare class NodeTrustBaseLoader extends BaseTrustBaseLoader {
+    private filePath?;
+    constructor(filePathOrNetwork?: string | NetworkType);
+    protected loadFromExternal(): Promise<unknown | null>;
+}
+/**
+ * Create Node.js TrustBase loader
+ */
+declare function createNodeTrustBaseLoader(filePathOrNetwork?: string | NetworkType): TrustBaseLoader$1;
+/**
+ * Create UnicityAggregatorProvider with Node.js TrustBase loader
+ */
+declare function createUnicityAggregatorProvider(config: Omit<UnicityAggregatorProviderConfig, 'trustBaseLoader'> & {
+    trustBasePath?: string;
+    network?: NetworkType;
+}): UnicityAggregatorProvider;
+/** @deprecated Use createUnicityAggregatorProvider instead */
+declare const createUnicityOracleProvider: typeof createUnicityAggregatorProvider;
+
 /**
  * Shared Configuration Interfaces
  * Base types extended by platform-specific implementations
@@ -1088,4 +1164,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, 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 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 };