@unicitylabs/sphere-sdk 0.1.8 → 0.2.0

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

@@ -33,6 +33,20 @@ interface Identity {
 interface FullIdentity extends Identity {
     readonly privateKey: string;
 }
+/**
+ * Minimal data stored in persistent storage for a tracked address.
+ * Only contains user state — derived fields are computed on load.
+ */
+interface TrackedAddressEntry {
+    /** HD derivation index (0, 1, 2, ...) */
+    readonly index: number;
+    /** Whether this address is hidden from UI display */
+    hidden: boolean;
+    /** Timestamp (ms) when this address was first activated */
+    readonly createdAt: number;
+    /** Timestamp (ms) of last modification */
+    updatedAt: number;
+}
 
 /**
  * Storage Provider Interface
@@ -72,6 +86,14 @@ interface StorageProvider extends BaseProvider {
      * Clear all keys with optional prefix filter
      */
     clear(prefix?: string): Promise<void>;
+    /**
+     * Save tracked addresses (only user state: index, hidden, timestamps)
+     */
+    saveTrackedAddresses(entries: TrackedAddressEntry[]): Promise<void>;
+    /**
+     * Load tracked addresses
+     */
+    loadTrackedAddresses(): Promise<TrackedAddressEntry[]>;
 }
 /**
  * Storage result types
@@ -236,6 +258,8 @@ declare class FileStorageProvider implements StorageProvider {
     has(key: string): Promise<boolean>;
     keys(prefix?: string): Promise<string[]>;
     clear(prefix?: string): Promise<void>;
+    saveTrackedAddresses(entries: TrackedAddressEntry[]): Promise<void>;
+    loadTrackedAddresses(): Promise<TrackedAddressEntry[]>;
     /**
      * Get full storage key with address prefix for per-address keys
      */
@@ -276,6 +300,7 @@ declare class FileTokenStorageProvider implements TokenStorageProvider<TxfStorag
     load(): Promise<LoadResult<TxfStorageDataBase>>;
     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>;
@@ -318,15 +343,36 @@ interface TransportProvider extends BaseProvider {
      * @returns Unsubscribe function
      */
     onTokenTransfer(handler: TokenTransferHandler): () => void;
+    /**
+     * Resolve any identifier to full peer information.
+     * Accepts @nametag, bare nametag, DIRECT://, PROXY://, L1 address, chain pubkey, or transport pubkey.
+     * @param identifier - Any supported identifier format
+     * @returns PeerInfo or null if not found
+     */
+    resolve?(identifier: string): Promise<PeerInfo | null>;
     /**
      * Resolve nametag to public key
      */
     resolveNametag?(nametag: string): Promise<string | null>;
     /**
-     * Resolve nametag to full address information
+     * Resolve nametag to full peer information
      * Returns transportPubkey, chainPubkey, l1Address, directAddress, proxyAddress
      */
-    resolveNametagInfo?(nametag: string): Promise<NametagInfo | null>;
+    resolveNametagInfo?(nametag: string): Promise<PeerInfo | null>;
+    /**
+     * Resolve a DIRECT://, PROXY://, or L1 address to full peer info.
+     * Performs reverse lookup: address → binding event → PeerInfo.
+     * @param address - L3 address (DIRECT://... or PROXY://...) or L1 address (alpha1...)
+     * @returns PeerInfo or null if no binding found for this address
+     */
+    resolveAddressInfo?(address: string): Promise<PeerInfo | null>;
+    /**
+     * Resolve transport pubkey to full peer info.
+     * Queries binding events authored by the given transport pubkey.
+     * @param transportPubkey - Transport-specific pubkey (e.g. 64-char hex string)
+     * @returns PeerInfo or null if no binding found
+     */
+    resolveTransportPubkeyInfo?(transportPubkey: string): Promise<PeerInfo | null>;
     /**
      * Recover nametag for current identity by decrypting stored encrypted nametag
      * Used after wallet import to recover associated nametag
@@ -334,14 +380,20 @@ interface TransportProvider extends BaseProvider {
      */
     recoverNametag?(): Promise<string | null>;
     /**
+     * Publish identity binding event.
+     * Without nametag: publishes base binding (chainPubkey, l1Address, directAddress).
+     * With nametag: adds nametag hash, proxy address, encrypted nametag for recovery.
+     * Uses parameterized replaceable event (kind 30078, d=hash(nostrPubkey)).
+     * @returns true if successful, false if nametag is taken by another pubkey
+     */
+    publishIdentityBinding?(chainPubkey: string, l1Address: string, directAddress: string, nametag?: string): Promise<boolean>;
+    /**
+     * @deprecated Use publishIdentityBinding instead
      * 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, chainPubkey: string, directAddress: string): Promise<boolean>;
     /**
+     * @deprecated Use publishIdentityBinding instead
      * Publish nametag binding
      */
     publishNametag?(nametag: string, address: string): Promise<void>;
@@ -401,7 +453,54 @@ interface TransportProvider extends BaseProvider {
      * Check if a relay is currently connected
      */
     isRelayConnected?(relayUrl: string): boolean;
+    /**
+     * Send an instant split bundle to a recipient.
+     * This is a specialized method for INSTANT_SPLIT V5 bundles.
+     *
+     * @param recipientTransportPubkey - Transport-specific pubkey for messaging
+     * @param bundle - The InstantSplitBundleV5 to send
+     * @returns Event ID
+     */
+    sendInstantSplitBundle?(recipientTransportPubkey: string, bundle: InstantSplitBundlePayload): Promise<string>;
+    /**
+     * Subscribe to incoming instant split bundles.
+     *
+     * @param handler - Handler for received bundles
+     * @returns Unsubscribe function
+     */
+    onInstantSplitReceived?(handler: InstantSplitBundleHandler): () => void;
+}
+/**
+ * Payload for sending instant split bundles
+ */
+interface InstantSplitBundlePayload {
+    /** The bundle JSON string (InstantSplitBundleV5 serialized) */
+    bundle: string;
+    /** Optional memo */
+    memo?: string;
+    /** Sender info */
+    sender?: {
+        transportPubkey: string;
+        nametag?: string;
+    };
 }
+/**
+ * Incoming instant split bundle
+ */
+interface IncomingInstantSplitBundle {
+    /** Event ID */
+    id: string;
+    /** Transport-specific pubkey of sender */
+    senderTransportPubkey: string;
+    /** The bundle JSON string */
+    bundle: string;
+    /** Timestamp */
+    timestamp: number;
+}
+/**
+ * Handler for instant split bundles
+ */
+type InstantSplitBundleHandler = (bundle: IncomingInstantSplitBundle) => void;
 interface IncomingMessage {
     id: string;
     /** Transport-specific pubkey of sender */
@@ -510,12 +609,13 @@ interface TransportEvent {
 }
 type TransportEventCallback = (event: TransportEvent) => void;
 /**
- * Full nametag address information
- * Used for resolving nametag to all address formats
+ * Resolved peer identity information.
+ * Returned by resolve methods — contains all public address formats for a peer.
+ * Fields nametag and proxyAddress are optional (only present if nametag is registered).
  */
-interface NametagInfo {
-    /** Nametag name (without @) */
-    nametag: string;
+interface PeerInfo {
+    /** Nametag name (without @), if registered */
+    nametag?: string;
     /** Transport-specific pubkey (for messaging/encryption) */
     transportPubkey: string;
     /** 33-byte compressed secp256k1 public key (for L3 chain) */
@@ -524,8 +624,8 @@ interface NametagInfo {
     l1Address: string;
     /** L3 DIRECT address (DIRECT://...) */
     directAddress: string;
-    /** L3 PROXY address derived from nametag hash (PROXY:...) */
-    proxyAddress: string;
+    /** L3 PROXY address derived from nametag hash (PROXY:...), only if nametag registered */
+    proxyAddress?: string;
     /** Event timestamp */
     timestamp: number;
 }
@@ -656,14 +756,42 @@ declare class NostrTransportProvider implements TransportProvider {
     onPaymentRequest(handler: PaymentRequestHandler): () => void;
     sendPaymentRequestResponse(recipientPubkey: string, payload: PaymentRequestResponsePayload): Promise<string>;
     onPaymentRequestResponse(handler: PaymentRequestResponseHandler): () => void;
+    /**
+     * Resolve any identifier to full peer information.
+     * Routes to the appropriate specific resolve method based on identifier format.
+     */
+    resolve(identifier: string): Promise<PeerInfo | null>;
     resolveNametag(nametag: string): Promise<string | null>;
-    resolveNametagInfo(nametag: string): Promise<NametagInfo | null>;
+    resolveNametagInfo(nametag: string): Promise<PeerInfo | null>;
+    /**
+     * Resolve a DIRECT://, PROXY://, or L1 address to full peer info.
+     * Performs reverse lookup: hash(address) → query '#t' tag → parse binding event.
+     * Works with both new identity binding events and legacy nametag binding events.
+     */
+    resolveAddressInfo(address: string): Promise<PeerInfo | null>;
+    /**
+     * Resolve transport pubkey (Nostr pubkey) to full peer info.
+     * Queries binding events authored by the given pubkey.
+     */
+    resolveTransportPubkeyInfo(transportPubkey: string): Promise<PeerInfo | 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>;
+    /**
+     * Publish identity binding event on Nostr.
+     * Without nametag: publishes base binding (chainPubkey, l1Address, directAddress).
+     * With nametag: also publishes nametag hash, proxy address, encrypted nametag for recovery.
+     *
+     * Uses kind 30078 parameterized replaceable event with d=SHA256('unicity:identity:' + nostrPubkey).
+     * Each HD address index has its own Nostr key → its own binding event.
+     *
+     * @returns true if successful, false if nametag is taken by another pubkey
+     */
+    publishIdentityBinding(chainPubkey: string, l1Address: string, directAddress: string, nametag?: string): Promise<boolean>;
+    /** @deprecated Use publishIdentityBinding instead */
     publishNametag(nametag: string, address: string): Promise<void>;
     registerNametag(nametag: string, _publicKey: string, directAddress?: string): Promise<boolean>;
     private broadcastSubscriptions;
@@ -1025,6 +1153,65 @@ declare function createUnicityAggregatorProvider(config: Omit<UnicityAggregatorP
 /** @deprecated Use createUnicityAggregatorProvider instead */
 declare const createUnicityOracleProvider: typeof createUnicityAggregatorProvider;
 
+/**
+ * Price Provider Interface
+ *
+ * Platform-independent abstraction for fetching token market prices.
+ * Does not extend BaseProvider — stateless HTTP client with internal caching.
+ */
+/**
+ * Supported price provider platforms
+ */
+type PricePlatform = 'coingecko';
+/**
+ * Price data for a single token
+ */
+interface TokenPrice {
+    /** Token name used by the price platform (e.g., "bitcoin") */
+    readonly tokenName: string;
+    /** Price in USD */
+    readonly priceUsd: number;
+    /** Price in EUR (if available) */
+    readonly priceEur?: number;
+    /** 24h price change percentage (if available) */
+    readonly change24h?: number;
+    /** Timestamp when this price was fetched */
+    readonly timestamp: number;
+}
+/**
+ * Price data provider
+ *
+ * Fetches current market prices for tokens. Implementations handle
+ * caching internally to avoid excessive API calls.
+ *
+ * @example
+ * ```ts
+ * const provider = new CoinGeckoPriceProvider({ apiKey: 'CG-xxx' });
+ * const prices = await provider.getPrices(['bitcoin', 'ethereum']);
+ * console.log(prices.get('bitcoin')?.priceUsd); // 97500
+ * ```
+ */
+interface PriceProvider {
+    /** Platform identifier (e.g., 'coingecko') */
+    readonly platform: PricePlatform;
+    /**
+     * Get prices for multiple tokens by their platform-compatible names
+     * @param tokenNames - Array of token names (e.g., ['bitcoin', 'ethereum'])
+     * @returns Map of token name to price data
+     */
+    getPrices(tokenNames: string[]): Promise<Map<string, TokenPrice>>;
+    /**
+     * Get price for a single token
+     * @param tokenName - Token name (e.g., 'bitcoin')
+     * @returns Token price or null if not available
+     */
+    getPrice(tokenName: string): Promise<TokenPrice | null>;
+    /**
+     * Clear cached prices
+     */
+    clearCache(): void;
+}
+
 /**
  * Shared Configuration Interfaces
  * Base types extended by platform-specific implementations
@@ -1080,6 +1267,23 @@ interface L1Config {
     /** Enable vesting classification */
     enableVesting?: boolean;
 }
+/**
+ * Base price provider configuration
+ */
+interface BasePriceConfig {
+    /** Which price platform to use (default: 'coingecko') */
+    platform?: PricePlatform;
+    /** API key for the price platform (optional for free tiers) */
+    apiKey?: string;
+    /** Custom base URL (e.g., for CORS proxy in browser environments) */
+    baseUrl?: string;
+    /** Cache TTL in milliseconds (default: 60000) */
+    cacheTtlMs?: number;
+    /** Request timeout in milliseconds (default: 10000) */
+    timeout?: number;
+    /** Enable debug logging */
+    debug?: boolean;
+}
 /**
  * Base providers result
  * Common structure for all platforms
@@ -1091,6 +1295,8 @@ interface BaseProviders {
     oracle: OracleProvider;
     /** L1 configuration (for passing to Sphere.init) */
     l1?: L1Config;
+    /** Price provider (optional — enables fiat value display) */
+    price?: PriceProvider;
 }
 
 /**
@@ -1126,6 +1332,8 @@ interface NodeProvidersConfig {
     oracle?: NodeOracleConfig;
     /** L1 (ALPHA blockchain) configuration */
     l1?: NodeL1Config;
+    /** Price provider configuration (optional — enables fiat value display) */
+    price?: BasePriceConfig;
 }
 interface NodeProviders {
     storage: StorageProvider;
@@ -1134,6 +1342,8 @@ interface NodeProviders {
     oracle: OracleProvider;
     /** L1 configuration (for passing to Sphere.init) */
     l1?: L1Config;
+    /** Price provider (optional — enables fiat value display) */
+    price?: PriceProvider;
 }
 /**
  * Create all Node.js providers with default configuration