@unicitylabs/sphere-sdk 0.3.9 → 0.4.2

package/dist/core/index.d.cts

@@ -655,6 +655,11 @@ interface BroadcastMessage {
     readonly timestamp: number;
     readonly tags?: string[];
 }
+interface ComposingIndicator {
+    readonly senderPubkey: string;
+    readonly senderNametag?: string;
+    readonly expiresIn: number;
+}
 /**
  * Minimal data stored in persistent storage for a tracked address.
  * Only contains user state — derived fields are computed on load.
@@ -685,7 +690,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:read' | 'message:typing' | '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';
+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:read' | 'message:typing' | 'composing:started' | '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;
@@ -705,6 +710,7 @@ interface SphereEventMap {
         senderNametag?: string;
         timestamp: number;
     };
+    'composing:started': ComposingIndicator;
     'message:broadcast': BroadcastMessage;
     'sync:started': {
         source: string;
@@ -1053,6 +1059,17 @@ interface TransportProvider extends BaseProvider {
      * @returns Unsubscribe function
      */
     onTypingIndicator?(handler: TypingIndicatorHandler): () => void;
+    /**
+     * Send composing indicator to a recipient using NIP-44 encrypted gift wrap
+     * @param recipientTransportPubkey - Transport pubkey of the conversation partner
+     * @param content - JSON payload with senderNametag and expiresIn
+     */
+    sendComposingIndicator?(recipientTransportPubkey: string, content: string): Promise<void>;
+    /**
+     * Subscribe to incoming composing indicators
+     * @returns Unsubscribe function
+     */
+    onComposing?(handler: ComposingHandler): () => void;
     /**
      * Get list of configured relay URLs
      */
@@ -1277,6 +1294,7 @@ interface IncomingTypingIndicator {
     timestamp: number;
 }
 type TypingIndicatorHandler = (indicator: IncomingTypingIndicator) => void;
+type ComposingHandler = (indicator: ComposingIndicator) => void;
 
 /**
  * L1 Payments Sub-Module
@@ -2401,6 +2419,13 @@ declare class PaymentsModule {
      * Remove all nametag data from memory and storage.
      */
     clearNametag(): Promise<void>;
+    /**
+     * Reload nametag data from storage providers into memory.
+     *
+     * Used as a recovery mechanism when `this.nametags` is unexpectedly empty
+     * (e.g., wiped by sync or race condition) but nametag data exists in storage.
+     */
+    private reloadNametagsFromStorage;
     /**
      * Mint a nametag token on-chain (like Sphere wallet and lottery)
      * This creates the nametag token required for receiving tokens via PROXY addresses
@@ -2492,6 +2517,11 @@ declare class PaymentsModule {
      * Create SigningService from identity private key
      */
     private createSigningService;
+    /**
+     * Get the wallet's signing public key (used for token ownership predicates).
+     * This is the key that token state predicates are checked against.
+     */
+    getSigningPublicKey(): Promise<Uint8Array>;
     /**
      * Create DirectAddress from a public key using UnmaskedPredicateReference
      */
@@ -2556,11 +2586,24 @@ declare class PaymentsModule {
 interface CommunicationsModuleConfig {
     /** Auto-save messages */
     autoSave?: boolean;
-    /** Max messages in memory */
+    /** Max messages in memory (global cap) */
     maxMessages?: number;
+    /** Max messages per conversation (default: 200) */
+    maxPerConversation?: number;
     /** Enable read receipts */
     readReceipts?: boolean;
 }
+interface ConversationPage {
+    messages: DirectMessage[];
+    hasMore: boolean;
+    oldestTimestamp: number | null;
+}
+interface GetConversationPageOptions {
+    /** Max messages to return (default: 20) */
+    limit?: number;
+    /** Return messages older than this timestamp */
+    before?: number;
+}
 interface CommunicationsModuleDependencies {
     identity: FullIdentity;
     storage: StorageProvider;
@@ -2573,8 +2616,10 @@ declare class CommunicationsModule {
     private messages;
     private broadcasts;
     private unsubscribeMessages;
+    private unsubscribeComposing;
     private broadcastSubscriptions;
     private dmHandlers;
+    private composingHandlers;
     private broadcastHandlers;
     constructor(config?: CommunicationsModuleConfig);
     /**
@@ -2582,7 +2627,10 @@ declare class CommunicationsModule {
      */
     initialize(deps: CommunicationsModuleDependencies): void;
     /**
-     * Load messages from storage
+     * Load messages from storage.
+     * Uses per-address key (STORAGE_KEYS_ADDRESS.MESSAGES) which is automatically
+     * scoped by LocalStorageProvider to sphere_DIRECT_xxx_yyy_messages.
+     * Falls back to legacy global 'direct_messages' key for migration.
      */
     load(): Promise<void>;
     /**
@@ -2609,10 +2657,28 @@ declare class CommunicationsModule {
      * Get unread count
      */
     getUnreadCount(peerPubkey?: string): number;
+    /**
+     * Get a page of messages from a conversation (for lazy loading).
+     * Returns messages in chronological order with a cursor for loading older messages.
+     */
+    getConversationPage(peerPubkey: string, options?: GetConversationPageOptions): ConversationPage;
+    /**
+     * Delete all messages in a conversation with a peer
+     */
+    deleteConversation(peerPubkey: string): Promise<void>;
     /**
      * Send typing indicator to a peer
      */
     sendTypingIndicator(peerPubkey: string): Promise<void>;
+    /**
+     * Send a composing indicator to a peer.
+     * Fire-and-forget — does not save to message history.
+     */
+    sendComposingIndicator(recipientPubkeyOrNametag: string): Promise<void>;
+    /**
+     * Subscribe to incoming composing indicators
+     */
+    onComposingIndicator(handler: (indicator: ComposingIndicator) => void): () => void;
     /**
      * Subscribe to incoming DMs
      */
@@ -2634,6 +2700,7 @@ declare class CommunicationsModule {
      */
     onBroadcast(handler: (message: BroadcastMessage) => void): () => void;
     private handleIncomingMessage;
+    private handleComposingIndicator;
     private handleIncomingBroadcast;
     private save;
     private pruneIfNeeded;
@@ -2761,6 +2828,146 @@ declare class GroupChatModule {
     private randomId;
 }
 
+/**
+ * Market Module Types
+ * Intent bulletin board for posting and discovering intents,
+ * plus real-time feed subscription.
+ */
+type IntentType = 'buy' | 'sell' | 'service' | 'announcement' | 'other' | (string & {});
+type IntentStatus = 'active' | 'closed' | 'expired';
+interface MarketModuleConfig {
+    /** Market API base URL (default: https://market-api.unicity.network) */
+    apiUrl?: string;
+    /** Request timeout in ms (default: 30000) */
+    timeout?: number;
+}
+interface MarketModuleDependencies {
+    identity: FullIdentity;
+    emitEvent: <T extends SphereEventType>(type: T, data: SphereEventMap[T]) => void;
+}
+interface PostIntentRequest {
+    description: string;
+    intentType: IntentType;
+    category?: string;
+    price?: number;
+    currency?: string;
+    location?: string;
+    contactHandle?: string;
+    expiresInDays?: number;
+}
+interface PostIntentResult {
+    intentId: string;
+    message: string;
+    expiresAt: string;
+}
+interface MarketIntent {
+    id: string;
+    intentType: IntentType;
+    category?: string;
+    price?: string;
+    currency: string;
+    location?: string;
+    status: IntentStatus;
+    createdAt: string;
+    expiresAt: string;
+}
+interface SearchIntentResult {
+    id: string;
+    score: number;
+    agentNametag?: string;
+    agentPublicKey: string;
+    description: string;
+    intentType: IntentType;
+    category?: string;
+    price?: number;
+    currency: string;
+    location?: string;
+    contactMethod: string;
+    contactHandle?: string;
+    createdAt: string;
+    expiresAt: string;
+}
+interface SearchFilters {
+    intentType?: IntentType;
+    category?: string;
+    minPrice?: number;
+    maxPrice?: number;
+    location?: string;
+    /** Minimum similarity score (0–1). Results below this threshold are excluded (client-side). */
+    minScore?: number;
+}
+interface SearchOptions {
+    filters?: SearchFilters;
+    limit?: number;
+}
+interface SearchResult {
+    intents: SearchIntentResult[];
+    count: number;
+}
+/** A listing broadcast on the live feed */
+interface FeedListing {
+    id: string;
+    title: string;
+    descriptionPreview: string;
+    agentName: string;
+    agentId: number;
+    type: IntentType;
+    createdAt: string;
+}
+/** WebSocket message: initial batch of recent listings */
+interface FeedInitialMessage {
+    type: 'initial';
+    listings: FeedListing[];
+}
+/** WebSocket message: single new listing */
+interface FeedNewMessage {
+    type: 'new';
+    listing: FeedListing;
+}
+type FeedMessage = FeedInitialMessage | FeedNewMessage;
+/** Callback for live feed events */
+type FeedListener = (message: FeedMessage) => void;
+
+declare class MarketModule {
+    private readonly apiUrl;
+    private readonly timeout;
+    private identity;
+    private registered;
+    constructor(config?: MarketModuleConfig);
+    /** Called by Sphere after construction */
+    initialize(deps: MarketModuleDependencies): void;
+    /** No-op — stateless module */
+    load(): Promise<void>;
+    /** No-op — stateless module */
+    destroy(): void;
+    /** Post a new intent (agent is auto-registered on first post) */
+    postIntent(intent: PostIntentRequest): Promise<PostIntentResult>;
+    /** Semantic search for intents (public — no auth required) */
+    search(query: string, opts?: SearchOptions): Promise<SearchResult>;
+    /** List own intents (authenticated) */
+    getMyIntents(): Promise<MarketIntent[]>;
+    /** Close (delete) an intent */
+    closeIntent(intentId: string): Promise<void>;
+    /** Fetch the most recent listings via REST (public — no auth required) */
+    getRecentListings(): Promise<FeedListing[]>;
+    /**
+     * Subscribe to the live listing feed via WebSocket.
+     * Returns an unsubscribe function that closes the connection.
+     *
+     * Requires a WebSocket implementation — works natively in browsers
+     * and in Node.js 21+ (or with the `ws` package).
+     */
+    subscribeFeed(listener: FeedListener): () => void;
+    private ensureIdentity;
+    /** Register the agent's public key with the server (idempotent) */
+    private ensureRegistered;
+    private parseResponse;
+    private apiPost;
+    private apiGet;
+    private apiDelete;
+    private apiPublicPost;
+}
+
 /** Network configurations */
 declare const NETWORKS: {
     readonly mainnet: {
@@ -2904,6 +3111,8 @@ interface SphereCreateOptions {
     network?: NetworkType;
     /** Group chat configuration (NIP-29). Omit to disable groupchat. */
     groupChat?: GroupChatModuleConfig | boolean;
+    /** Market module configuration. true = enable with defaults, object = custom config. */
+    market?: MarketModuleConfig | boolean;
     /** Optional password to encrypt the wallet. If omitted, mnemonic is stored as plaintext. */
     password?: string;
 }
@@ -2929,6 +3138,8 @@ interface SphereLoadOptions {
     network?: NetworkType;
     /** Group chat configuration (NIP-29). Omit to disable groupchat. */
     groupChat?: GroupChatModuleConfig | boolean;
+    /** Market module configuration. true = enable with defaults, object = custom config. */
+    market?: MarketModuleConfig | boolean;
     /** Optional password to decrypt the wallet. Must match the password used during creation. */
     password?: string;
 }
@@ -2962,6 +3173,8 @@ interface SphereImportOptions {
     price?: PriceProvider;
     /** Group chat configuration (NIP-29). Omit to disable groupchat. */
     groupChat?: GroupChatModuleConfig | boolean;
+    /** Market module configuration. true = enable with defaults, object = custom config. */
+    market?: MarketModuleConfig | boolean;
     /** Optional password to encrypt the wallet. If omitted, mnemonic/key is stored as plaintext. */
     password?: string;
 }
@@ -3009,6 +3222,8 @@ interface SphereInitOptions {
      * - Omit/undefined: No groupchat module
      */
     groupChat?: GroupChatModuleConfig | boolean;
+    /** Market module configuration. true = enable with defaults, object = custom config. */
+    market?: MarketModuleConfig | boolean;
     /** Optional password to encrypt/decrypt the wallet. If omitted, mnemonic is stored as plaintext. */
     password?: string;
 }
@@ -3048,6 +3263,7 @@ declare class Sphere {
     private _payments;
     private _communications;
     private _groupChat;
+    private _market;
     private eventHandlers;
     private _disabledProviders;
     private _providerEventCleanups;
@@ -3095,6 +3311,13 @@ declare class Sphere {
      * (different input shape: { enabled?, relays? }). Both fill relay URLs from network defaults.
      */
     private static resolveGroupChatConfig;
+    /**
+     * Resolve market module config from Sphere.init() options.
+     * - `true` → enable with default API URL
+     * - `MarketModuleConfig` → pass through
+     * - `undefined` → no market module
+     */
+    private static resolveMarketConfig;
     /**
      * Configure TokenRegistry in the main bundle context.
      *
@@ -3163,6 +3386,8 @@ declare class Sphere {
     get communications(): CommunicationsModule;
     /** Group chat module (NIP-29). Null if not configured. */
     get groupChat(): GroupChatModule | null;
+    /** Market module (intent bulletin board). Null if not configured. */
+    get market(): MarketModule | null;
     /** Current identity (public info only) */
     get identity(): Identity | null;
     /** Is ready */