@unicitylabs/sphere-sdk 0.3.4 → 0.3.6

package/dist/core/index.d.cts

@@ -2704,6 +2704,154 @@ 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;
+
+/**
+ * Market Module
+ *
+ * Intent bulletin board — post and discover intents (buy, sell,
+ * service, announcement, other) with secp256k1-signed requests
+ * tied to the wallet identity. Includes real-time feed via WebSocket.
+ */
+
+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: {
@@ -2713,6 +2861,7 @@ declare const NETWORKS: {
         readonly ipfsGateways: readonly ["https://unicity-ipfs1.dyndns.org"];
         readonly electrumUrl: "wss://fulcrum.alpha.unicity.network:50004";
         readonly groupRelays: readonly ["wss://sphere-relay.unicity.network"];
+        readonly tokenRegistryUrl: "https://raw.githubusercontent.com/unicitynetwork/unicity-ids/refs/heads/main/unicity-ids.testnet.json";
     };
     readonly testnet: {
         readonly name: "Testnet";
@@ -2721,6 +2870,7 @@ declare const NETWORKS: {
         readonly ipfsGateways: readonly ["https://unicity-ipfs1.dyndns.org"];
         readonly electrumUrl: "wss://fulcrum.alpha.testnet.unicity.network:50004";
         readonly groupRelays: readonly ["wss://sphere-relay.unicity.network"];
+        readonly tokenRegistryUrl: "https://raw.githubusercontent.com/unicitynetwork/unicity-ids/refs/heads/main/unicity-ids.testnet.json";
     };
     readonly dev: {
         readonly name: "Development";
@@ -2729,6 +2879,7 @@ declare const NETWORKS: {
         readonly ipfsGateways: readonly ["https://unicity-ipfs1.dyndns.org"];
         readonly electrumUrl: "wss://fulcrum.alpha.testnet.unicity.network:50004";
         readonly groupRelays: readonly ["wss://sphere-relay.unicity.network"];
+        readonly tokenRegistryUrl: "https://raw.githubusercontent.com/unicitynetwork/unicity-ids/refs/heads/main/unicity-ids.testnet.json";
     };
 };
 type NetworkType = keyof typeof NETWORKS;
@@ -2846,6 +2997,8 @@ interface SphereCreateOptions {
     groupChat?: GroupChatModuleConfig | boolean;
     /** Optional password to encrypt the wallet. If omitted, mnemonic is stored as plaintext. */
     password?: string;
+    /** Market module configuration. true = enable with defaults, object = custom config. */
+    market?: MarketModuleConfig | boolean;
 }
 /** Options for loading existing wallet */
 interface SphereLoadOptions {
@@ -2871,6 +3024,8 @@ interface SphereLoadOptions {
     groupChat?: GroupChatModuleConfig | boolean;
     /** Optional password to decrypt the wallet. Must match the password used during creation. */
     password?: string;
+    /** Market module configuration. true = enable with defaults, object = custom config. */
+    market?: MarketModuleConfig | boolean;
 }
 /** Options for importing a wallet */
 interface SphereImportOptions {
@@ -2904,6 +3059,8 @@ interface SphereImportOptions {
     groupChat?: GroupChatModuleConfig | boolean;
     /** Optional password to encrypt the wallet. If omitted, mnemonic/key is stored as plaintext. */
     password?: string;
+    /** Market module configuration. true = enable with defaults, object = custom config. */
+    market?: MarketModuleConfig | boolean;
 }
 /** L1 (ALPHA blockchain) configuration */
 interface L1Config {
@@ -2951,6 +3108,8 @@ interface SphereInitOptions {
     groupChat?: GroupChatModuleConfig | boolean;
     /** Optional password to encrypt/decrypt the wallet. If omitted, mnemonic is stored as plaintext. */
     password?: string;
+    /** Market module configuration. true = enable with defaults, object = custom config. */
+    market?: MarketModuleConfig | boolean;
 }
 /** Result of init operation */
 interface SphereInitResult {
@@ -2988,6 +3147,7 @@ declare class Sphere {
     private _payments;
     private _communications;
     private _groupChat;
+    private _market;
     private eventHandlers;
     private _disabledProviders;
     private _providerEventCleanups;
@@ -3035,6 +3195,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 with defaults
+     * - `undefined` → no market module
+     */
+    private static resolveMarketConfig;
     /**
      * Create new wallet with mnemonic
      */
@@ -3093,6 +3260,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 */

package/dist/core/index.d.ts

@@ -2704,6 +2704,154 @@ 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;
+
+/**
+ * Market Module
+ *
+ * Intent bulletin board — post and discover intents (buy, sell,
+ * service, announcement, other) with secp256k1-signed requests
+ * tied to the wallet identity. Includes real-time feed via WebSocket.
+ */
+
+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: {
@@ -2713,6 +2861,7 @@ declare const NETWORKS: {
         readonly ipfsGateways: readonly ["https://unicity-ipfs1.dyndns.org"];
         readonly electrumUrl: "wss://fulcrum.alpha.unicity.network:50004";
         readonly groupRelays: readonly ["wss://sphere-relay.unicity.network"];
+        readonly tokenRegistryUrl: "https://raw.githubusercontent.com/unicitynetwork/unicity-ids/refs/heads/main/unicity-ids.testnet.json";
     };
     readonly testnet: {
         readonly name: "Testnet";
@@ -2721,6 +2870,7 @@ declare const NETWORKS: {
         readonly ipfsGateways: readonly ["https://unicity-ipfs1.dyndns.org"];
         readonly electrumUrl: "wss://fulcrum.alpha.testnet.unicity.network:50004";
         readonly groupRelays: readonly ["wss://sphere-relay.unicity.network"];
+        readonly tokenRegistryUrl: "https://raw.githubusercontent.com/unicitynetwork/unicity-ids/refs/heads/main/unicity-ids.testnet.json";
     };
     readonly dev: {
         readonly name: "Development";
@@ -2729,6 +2879,7 @@ declare const NETWORKS: {
         readonly ipfsGateways: readonly ["https://unicity-ipfs1.dyndns.org"];
         readonly electrumUrl: "wss://fulcrum.alpha.testnet.unicity.network:50004";
         readonly groupRelays: readonly ["wss://sphere-relay.unicity.network"];
+        readonly tokenRegistryUrl: "https://raw.githubusercontent.com/unicitynetwork/unicity-ids/refs/heads/main/unicity-ids.testnet.json";
     };
 };
 type NetworkType = keyof typeof NETWORKS;
@@ -2846,6 +2997,8 @@ interface SphereCreateOptions {
     groupChat?: GroupChatModuleConfig | boolean;
     /** Optional password to encrypt the wallet. If omitted, mnemonic is stored as plaintext. */
     password?: string;
+    /** Market module configuration. true = enable with defaults, object = custom config. */
+    market?: MarketModuleConfig | boolean;
 }
 /** Options for loading existing wallet */
 interface SphereLoadOptions {
@@ -2871,6 +3024,8 @@ interface SphereLoadOptions {
     groupChat?: GroupChatModuleConfig | boolean;
     /** Optional password to decrypt the wallet. Must match the password used during creation. */
     password?: string;
+    /** Market module configuration. true = enable with defaults, object = custom config. */
+    market?: MarketModuleConfig | boolean;
 }
 /** Options for importing a wallet */
 interface SphereImportOptions {
@@ -2904,6 +3059,8 @@ interface SphereImportOptions {
     groupChat?: GroupChatModuleConfig | boolean;
     /** Optional password to encrypt the wallet. If omitted, mnemonic/key is stored as plaintext. */
     password?: string;
+    /** Market module configuration. true = enable with defaults, object = custom config. */
+    market?: MarketModuleConfig | boolean;
 }
 /** L1 (ALPHA blockchain) configuration */
 interface L1Config {
@@ -2951,6 +3108,8 @@ interface SphereInitOptions {
     groupChat?: GroupChatModuleConfig | boolean;
     /** Optional password to encrypt/decrypt the wallet. If omitted, mnemonic is stored as plaintext. */
     password?: string;
+    /** Market module configuration. true = enable with defaults, object = custom config. */
+    market?: MarketModuleConfig | boolean;
 }
 /** Result of init operation */
 interface SphereInitResult {
@@ -2988,6 +3147,7 @@ declare class Sphere {
     private _payments;
     private _communications;
     private _groupChat;
+    private _market;
     private eventHandlers;
     private _disabledProviders;
     private _providerEventCleanups;
@@ -3035,6 +3195,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 with defaults
+     * - `undefined` → no market module
+     */
+    private static resolveMarketConfig;
     /**
      * Create new wallet with mnemonic
      */
@@ -3093,6 +3260,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 */