@unicitylabs/sphere-sdk 0.5.3 → 0.5.5

package/dist/core/index.d.cts

@@ -68,6 +68,42 @@ interface CreateGroupOptions {
     visibility?: GroupVisibility;
 }
 
+/**
+ * SDK Error Types
+ *
+ * Structured error codes for programmatic error handling in UI.
+ * UI can switch on error.code to show appropriate user-facing messages.
+ *
+ * @example
+ * ```ts
+ * import { SphereError } from '@unicitylabs/sphere-sdk';
+ *
+ * try {
+ *   await sphere.payments.send({ ... });
+ * } catch (err) {
+ *   if (err instanceof SphereError) {
+ *     switch (err.code) {
+ *       case 'INSUFFICIENT_BALANCE': showToast('Not enough funds'); break;
+ *       case 'INVALID_RECIPIENT': showToast('Recipient not found'); break;
+ *       case 'TRANSPORT_ERROR': showToast('Network connection issue'); break;
+ *       case 'TIMEOUT': showToast('Request timed out, try again'); break;
+ *       default: showToast(err.message);
+ *     }
+ *   }
+ * }
+ * ```
+ */
+type SphereErrorCode = 'NOT_INITIALIZED' | 'ALREADY_INITIALIZED' | 'INVALID_CONFIG' | 'INVALID_IDENTITY' | 'INSUFFICIENT_BALANCE' | 'INVALID_RECIPIENT' | 'TRANSFER_FAILED' | 'STORAGE_ERROR' | 'TRANSPORT_ERROR' | 'AGGREGATOR_ERROR' | 'VALIDATION_ERROR' | 'NETWORK_ERROR' | 'TIMEOUT' | 'DECRYPTION_ERROR' | 'MODULE_NOT_AVAILABLE';
+declare class SphereError extends Error {
+    readonly code: SphereErrorCode;
+    readonly cause?: unknown;
+    constructor(message: string, code: SphereErrorCode, cause?: unknown);
+}
+/**
+ * Type guard to check if an error is a SphereError
+ */
+declare function isSphereError(err: unknown): err is SphereError;
+
 /**
  * Cryptographic utilities for SDK2
  *
@@ -1957,7 +1993,6 @@ declare class PaymentsModule {
     getConfig(): Omit<Required<PaymentsModuleConfig>, 'l1'>;
     /** Price provider (optional) */
     private priceProvider;
-    private log;
     /**
      * Initialize module with dependencies
      */
@@ -3346,6 +3381,8 @@ interface SphereCreateOptions {
      * - false/undefined: no auto-discovery (default)
      */
     discoverAddresses?: boolean | DiscoverAddressesOptions;
+    /** Enable debug logging (default: false) */
+    debug?: boolean;
     /** Optional callback to report initialization progress steps */
     onProgress?: InitProgressCallback;
 }
@@ -3382,6 +3419,8 @@ interface SphereLoadOptions {
      * - false/undefined: no auto-discovery (default)
      */
     discoverAddresses?: boolean | DiscoverAddressesOptions;
+    /** Enable debug logging (default: false) */
+    debug?: boolean;
     /** Optional callback to report initialization progress steps */
     onProgress?: InitProgressCallback;
 }
@@ -3426,6 +3465,8 @@ interface SphereImportOptions {
      * - false/undefined: no auto-discovery (default)
      */
     discoverAddresses?: boolean | DiscoverAddressesOptions;
+    /** Enable debug logging (default: false) */
+    debug?: boolean;
     /** Optional callback to report initialization progress steps */
     onProgress?: InitProgressCallback;
 }
@@ -3485,6 +3526,8 @@ interface SphereInitOptions {
      * - false/undefined: no auto-discovery (default)
      */
     discoverAddresses?: boolean | DiscoverAddressesOptions;
+    /** Enable debug logging (default: false) */
+    debug?: boolean;
     /** Optional callback to report initialization progress steps */
     onProgress?: InitProgressCallback;
 }
@@ -4469,6 +4512,84 @@ declare function randomHex(byteLength: number): string;
  */
 declare function randomUUID(): string;
 
+/**
+ * Centralized SDK Logger
+ *
+ * A lightweight singleton logger that works across all tsup bundles
+ * by storing state on globalThis. Supports three log levels:
+ * - debug: detailed messages (only shown when debug=true)
+ * - warn: important warnings (ALWAYS shown regardless of debug flag)
+ * - error: critical errors (ALWAYS shown regardless of debug flag)
+ *
+ * Global debug flag enables all logging. Per-tag overrides allow
+ * granular control (e.g., only transport debug).
+ *
+ * @example
+ * ```ts
+ * import { logger } from '@unicitylabs/sphere-sdk';
+ *
+ * // Enable all debug logging
+ * logger.configure({ debug: true });
+ *
+ * // Enable only specific tags
+ * logger.setTagDebug('Nostr', true);
+ *
+ * // Usage in SDK classes
+ * logger.debug('Payments', 'Transfer started', { amount, recipient });
+ * logger.warn('Nostr', 'queryEvents timed out after 5s');
+ * logger.error('Sphere', 'Critical failure', error);
+ * ```
+ */
+type LogLevel = 'debug' | 'warn' | 'error';
+type LogHandler = (level: LogLevel, tag: string, message: string, ...args: unknown[]) => void;
+interface LoggerConfig {
+    /** Enable debug logging globally (default: false). When false, only warn and error messages are shown. */
+    debug?: boolean;
+    /** Custom log handler. If provided, replaces console output. Useful for tests or custom log sinks. */
+    handler?: LogHandler | null;
+}
+declare const logger: {
+    /**
+     * Configure the logger. Can be called multiple times (last write wins).
+     * Typically called by createBrowserProviders(), createNodeProviders(), or Sphere.init().
+     */
+    configure(config: LoggerConfig): void;
+    /**
+     * Enable/disable debug logging for a specific tag.
+     * Per-tag setting overrides the global debug flag.
+     *
+     * @example
+     * ```ts
+     * logger.setTagDebug('Nostr', true);  // enable only Nostr logs
+     * logger.setTagDebug('Nostr', false); // disable Nostr logs even if global debug=true
+     * ```
+     */
+    setTagDebug(tag: string, enabled: boolean): void;
+    /**
+     * Clear per-tag override, falling back to global debug flag.
+     */
+    clearTagDebug(tag: string): void;
+    /** Returns true if debug mode is enabled for the given tag (or globally). */
+    isDebugEnabled(tag?: string): boolean;
+    /**
+     * Debug-level log. Only shown when debug is enabled (globally or for this tag).
+     * Use for detailed operational information.
+     */
+    debug(tag: string, message: string, ...args: unknown[]): void;
+    /**
+     * Warning-level log. ALWAYS shown regardless of debug flag.
+     * Use for important but non-critical issues (timeouts, retries, degraded state).
+     */
+    warn(tag: string, message: string, ...args: unknown[]): void;
+    /**
+     * Error-level log. ALWAYS shown regardless of debug flag.
+     * Use for critical failures that should never be silenced.
+     */
+    error(tag: string, message: string, ...args: unknown[]): void;
+    /** Reset all logger state (debug flag, tags, handler). Primarily for tests. */
+    reset(): void;
+};
+
 /**
  * Network Health Check
  *
@@ -4566,4 +4687,4 @@ interface CheckNetworkHealthOptions {
  */
 declare function checkNetworkHealth(network?: NetworkType, options?: CheckNetworkHealthOptions): Promise<NetworkHealthResult>;
 
-export { type AddressInfo, CHARSET, type CheckNetworkHealthOptions, CurrencyUtils, DEFAULT_DERIVATION_PATH, DEFAULT_TOKEN_DECIMALS, type DerivedKey, type DiscoverAddressProgress, type DiscoverAddressesOptions, type DiscoverAddressesResult, type DiscoveredAddress, type EncryptedData, type EncryptionOptions, type InitProgress, type InitProgressCallback, type InitProgressStep, type KeyPair, type L1Config, type MasterKey, type ScanAddressProgress, type ScanAddressesOptions, type ScanAddressesResult, type ScannedAddressResult, Sphere, type SphereCreateOptions, type SphereImportOptions, type SphereInitOptions, type SphereInitResult, type SphereLoadOptions, base58Decode, base58Encode, bytesToHex, checkNetworkHealth, computeHash160, convertBits, createAddress, createBech32, createKeyPair, createSphere, decodeBech32, decrypt, decryptJson, decryptMnemonic, decryptSimple, decryptWithSalt, deriveAddressInfo, deriveChildKey, deriveKeyAtPath, deserializeEncrypted, discoverAddressesImpl, doubleSha256, ec, encodeBech32, encrypt, encryptMnemonic, encryptSimple, entropyToMnemonic, extractFromText, findPattern, formatAmount, generateAddressInfo, generateMasterKey, generateMnemonic, generateRandomKey, getAddressHrp, getPublicKey, getSphere, hash160, hash160ToBytes, hexToBytes, identityFromMnemonic, identityFromMnemonicSync, importSphere, initSphere, isEncryptedData, isValidBech32, isValidNametag, isValidPrivateKey, loadSphere, mnemonicToEntropy, mnemonicToSeed, mnemonicToSeedSync, privateKeyToAddressInfo, publicKeyToAddress, randomBytes, randomHex, randomUUID, ripemd160, scanAddressesImpl, serializeEncrypted, sha256, sleep, sphereExists, toHumanReadable, toSmallestUnit, validateMnemonic };
+export { type AddressInfo, CHARSET, type CheckNetworkHealthOptions, CurrencyUtils, DEFAULT_DERIVATION_PATH, DEFAULT_TOKEN_DECIMALS, type DerivedKey, type DiscoverAddressProgress, type DiscoverAddressesOptions, type DiscoverAddressesResult, type DiscoveredAddress, type EncryptedData, type EncryptionOptions, type InitProgress, type InitProgressCallback, type InitProgressStep, type KeyPair, type L1Config, type LogHandler, type LogLevel, type LoggerConfig, type MasterKey, type ScanAddressProgress, type ScanAddressesOptions, type ScanAddressesResult, type ScannedAddressResult, Sphere, type SphereCreateOptions, SphereError, type SphereErrorCode, type SphereImportOptions, type SphereInitOptions, type SphereInitResult, type SphereLoadOptions, base58Decode, base58Encode, bytesToHex, checkNetworkHealth, computeHash160, convertBits, createAddress, createBech32, createKeyPair, createSphere, decodeBech32, decrypt, decryptJson, decryptMnemonic, decryptSimple, decryptWithSalt, deriveAddressInfo, deriveChildKey, deriveKeyAtPath, deserializeEncrypted, discoverAddressesImpl, doubleSha256, ec, encodeBech32, encrypt, encryptMnemonic, encryptSimple, entropyToMnemonic, extractFromText, findPattern, formatAmount, generateAddressInfo, generateMasterKey, generateMnemonic, generateRandomKey, getAddressHrp, getPublicKey, getSphere, hash160, hash160ToBytes, hexToBytes, identityFromMnemonic, identityFromMnemonicSync, importSphere, initSphere, isEncryptedData, isSphereError, isValidBech32, isValidNametag, isValidPrivateKey, loadSphere, logger, mnemonicToEntropy, mnemonicToSeed, mnemonicToSeedSync, privateKeyToAddressInfo, publicKeyToAddress, randomBytes, randomHex, randomUUID, ripemd160, scanAddressesImpl, serializeEncrypted, sha256, sleep, sphereExists, toHumanReadable, toSmallestUnit, validateMnemonic };

package/dist/core/index.d.ts

@@ -68,6 +68,42 @@ interface CreateGroupOptions {
     visibility?: GroupVisibility;
 }
 
+/**
+ * SDK Error Types
+ *
+ * Structured error codes for programmatic error handling in UI.
+ * UI can switch on error.code to show appropriate user-facing messages.
+ *
+ * @example
+ * ```ts
+ * import { SphereError } from '@unicitylabs/sphere-sdk';
+ *
+ * try {
+ *   await sphere.payments.send({ ... });
+ * } catch (err) {
+ *   if (err instanceof SphereError) {
+ *     switch (err.code) {
+ *       case 'INSUFFICIENT_BALANCE': showToast('Not enough funds'); break;
+ *       case 'INVALID_RECIPIENT': showToast('Recipient not found'); break;
+ *       case 'TRANSPORT_ERROR': showToast('Network connection issue'); break;
+ *       case 'TIMEOUT': showToast('Request timed out, try again'); break;
+ *       default: showToast(err.message);
+ *     }
+ *   }
+ * }
+ * ```
+ */
+type SphereErrorCode = 'NOT_INITIALIZED' | 'ALREADY_INITIALIZED' | 'INVALID_CONFIG' | 'INVALID_IDENTITY' | 'INSUFFICIENT_BALANCE' | 'INVALID_RECIPIENT' | 'TRANSFER_FAILED' | 'STORAGE_ERROR' | 'TRANSPORT_ERROR' | 'AGGREGATOR_ERROR' | 'VALIDATION_ERROR' | 'NETWORK_ERROR' | 'TIMEOUT' | 'DECRYPTION_ERROR' | 'MODULE_NOT_AVAILABLE';
+declare class SphereError extends Error {
+    readonly code: SphereErrorCode;
+    readonly cause?: unknown;
+    constructor(message: string, code: SphereErrorCode, cause?: unknown);
+}
+/**
+ * Type guard to check if an error is a SphereError
+ */
+declare function isSphereError(err: unknown): err is SphereError;
+
 /**
  * Cryptographic utilities for SDK2
  *
@@ -1957,7 +1993,6 @@ declare class PaymentsModule {
     getConfig(): Omit<Required<PaymentsModuleConfig>, 'l1'>;
     /** Price provider (optional) */
     private priceProvider;
-    private log;
     /**
      * Initialize module with dependencies
      */
@@ -3346,6 +3381,8 @@ interface SphereCreateOptions {
      * - false/undefined: no auto-discovery (default)
      */
     discoverAddresses?: boolean | DiscoverAddressesOptions;
+    /** Enable debug logging (default: false) */
+    debug?: boolean;
     /** Optional callback to report initialization progress steps */
     onProgress?: InitProgressCallback;
 }
@@ -3382,6 +3419,8 @@ interface SphereLoadOptions {
      * - false/undefined: no auto-discovery (default)
      */
     discoverAddresses?: boolean | DiscoverAddressesOptions;
+    /** Enable debug logging (default: false) */
+    debug?: boolean;
     /** Optional callback to report initialization progress steps */
     onProgress?: InitProgressCallback;
 }
@@ -3426,6 +3465,8 @@ interface SphereImportOptions {
      * - false/undefined: no auto-discovery (default)
      */
     discoverAddresses?: boolean | DiscoverAddressesOptions;
+    /** Enable debug logging (default: false) */
+    debug?: boolean;
     /** Optional callback to report initialization progress steps */
     onProgress?: InitProgressCallback;
 }
@@ -3485,6 +3526,8 @@ interface SphereInitOptions {
      * - false/undefined: no auto-discovery (default)
      */
     discoverAddresses?: boolean | DiscoverAddressesOptions;
+    /** Enable debug logging (default: false) */
+    debug?: boolean;
     /** Optional callback to report initialization progress steps */
     onProgress?: InitProgressCallback;
 }
@@ -4469,6 +4512,84 @@ declare function randomHex(byteLength: number): string;
  */
 declare function randomUUID(): string;
 
+/**
+ * Centralized SDK Logger
+ *
+ * A lightweight singleton logger that works across all tsup bundles
+ * by storing state on globalThis. Supports three log levels:
+ * - debug: detailed messages (only shown when debug=true)
+ * - warn: important warnings (ALWAYS shown regardless of debug flag)
+ * - error: critical errors (ALWAYS shown regardless of debug flag)
+ *
+ * Global debug flag enables all logging. Per-tag overrides allow
+ * granular control (e.g., only transport debug).
+ *
+ * @example
+ * ```ts
+ * import { logger } from '@unicitylabs/sphere-sdk';
+ *
+ * // Enable all debug logging
+ * logger.configure({ debug: true });
+ *
+ * // Enable only specific tags
+ * logger.setTagDebug('Nostr', true);
+ *
+ * // Usage in SDK classes
+ * logger.debug('Payments', 'Transfer started', { amount, recipient });
+ * logger.warn('Nostr', 'queryEvents timed out after 5s');
+ * logger.error('Sphere', 'Critical failure', error);
+ * ```
+ */
+type LogLevel = 'debug' | 'warn' | 'error';
+type LogHandler = (level: LogLevel, tag: string, message: string, ...args: unknown[]) => void;
+interface LoggerConfig {
+    /** Enable debug logging globally (default: false). When false, only warn and error messages are shown. */
+    debug?: boolean;
+    /** Custom log handler. If provided, replaces console output. Useful for tests or custom log sinks. */
+    handler?: LogHandler | null;
+}
+declare const logger: {
+    /**
+     * Configure the logger. Can be called multiple times (last write wins).
+     * Typically called by createBrowserProviders(), createNodeProviders(), or Sphere.init().
+     */
+    configure(config: LoggerConfig): void;
+    /**
+     * Enable/disable debug logging for a specific tag.
+     * Per-tag setting overrides the global debug flag.
+     *
+     * @example
+     * ```ts
+     * logger.setTagDebug('Nostr', true);  // enable only Nostr logs
+     * logger.setTagDebug('Nostr', false); // disable Nostr logs even if global debug=true
+     * ```
+     */
+    setTagDebug(tag: string, enabled: boolean): void;
+    /**
+     * Clear per-tag override, falling back to global debug flag.
+     */
+    clearTagDebug(tag: string): void;
+    /** Returns true if debug mode is enabled for the given tag (or globally). */
+    isDebugEnabled(tag?: string): boolean;
+    /**
+     * Debug-level log. Only shown when debug is enabled (globally or for this tag).
+     * Use for detailed operational information.
+     */
+    debug(tag: string, message: string, ...args: unknown[]): void;
+    /**
+     * Warning-level log. ALWAYS shown regardless of debug flag.
+     * Use for important but non-critical issues (timeouts, retries, degraded state).
+     */
+    warn(tag: string, message: string, ...args: unknown[]): void;
+    /**
+     * Error-level log. ALWAYS shown regardless of debug flag.
+     * Use for critical failures that should never be silenced.
+     */
+    error(tag: string, message: string, ...args: unknown[]): void;
+    /** Reset all logger state (debug flag, tags, handler). Primarily for tests. */
+    reset(): void;
+};
+
 /**
  * Network Health Check
  *
@@ -4566,4 +4687,4 @@ interface CheckNetworkHealthOptions {
  */
 declare function checkNetworkHealth(network?: NetworkType, options?: CheckNetworkHealthOptions): Promise<NetworkHealthResult>;
 
-export { type AddressInfo, CHARSET, type CheckNetworkHealthOptions, CurrencyUtils, DEFAULT_DERIVATION_PATH, DEFAULT_TOKEN_DECIMALS, type DerivedKey, type DiscoverAddressProgress, type DiscoverAddressesOptions, type DiscoverAddressesResult, type DiscoveredAddress, type EncryptedData, type EncryptionOptions, type InitProgress, type InitProgressCallback, type InitProgressStep, type KeyPair, type L1Config, type MasterKey, type ScanAddressProgress, type ScanAddressesOptions, type ScanAddressesResult, type ScannedAddressResult, Sphere, type SphereCreateOptions, type SphereImportOptions, type SphereInitOptions, type SphereInitResult, type SphereLoadOptions, base58Decode, base58Encode, bytesToHex, checkNetworkHealth, computeHash160, convertBits, createAddress, createBech32, createKeyPair, createSphere, decodeBech32, decrypt, decryptJson, decryptMnemonic, decryptSimple, decryptWithSalt, deriveAddressInfo, deriveChildKey, deriveKeyAtPath, deserializeEncrypted, discoverAddressesImpl, doubleSha256, ec, encodeBech32, encrypt, encryptMnemonic, encryptSimple, entropyToMnemonic, extractFromText, findPattern, formatAmount, generateAddressInfo, generateMasterKey, generateMnemonic, generateRandomKey, getAddressHrp, getPublicKey, getSphere, hash160, hash160ToBytes, hexToBytes, identityFromMnemonic, identityFromMnemonicSync, importSphere, initSphere, isEncryptedData, isValidBech32, isValidNametag, isValidPrivateKey, loadSphere, mnemonicToEntropy, mnemonicToSeed, mnemonicToSeedSync, privateKeyToAddressInfo, publicKeyToAddress, randomBytes, randomHex, randomUUID, ripemd160, scanAddressesImpl, serializeEncrypted, sha256, sleep, sphereExists, toHumanReadable, toSmallestUnit, validateMnemonic };
+export { type AddressInfo, CHARSET, type CheckNetworkHealthOptions, CurrencyUtils, DEFAULT_DERIVATION_PATH, DEFAULT_TOKEN_DECIMALS, type DerivedKey, type DiscoverAddressProgress, type DiscoverAddressesOptions, type DiscoverAddressesResult, type DiscoveredAddress, type EncryptedData, type EncryptionOptions, type InitProgress, type InitProgressCallback, type InitProgressStep, type KeyPair, type L1Config, type LogHandler, type LogLevel, type LoggerConfig, type MasterKey, type ScanAddressProgress, type ScanAddressesOptions, type ScanAddressesResult, type ScannedAddressResult, Sphere, type SphereCreateOptions, SphereError, type SphereErrorCode, type SphereImportOptions, type SphereInitOptions, type SphereInitResult, type SphereLoadOptions, base58Decode, base58Encode, bytesToHex, checkNetworkHealth, computeHash160, convertBits, createAddress, createBech32, createKeyPair, createSphere, decodeBech32, decrypt, decryptJson, decryptMnemonic, decryptSimple, decryptWithSalt, deriveAddressInfo, deriveChildKey, deriveKeyAtPath, deserializeEncrypted, discoverAddressesImpl, doubleSha256, ec, encodeBech32, encrypt, encryptMnemonic, encryptSimple, entropyToMnemonic, extractFromText, findPattern, formatAmount, generateAddressInfo, generateMasterKey, generateMnemonic, generateRandomKey, getAddressHrp, getPublicKey, getSphere, hash160, hash160ToBytes, hexToBytes, identityFromMnemonic, identityFromMnemonicSync, importSphere, initSphere, isEncryptedData, isSphereError, isValidBech32, isValidNametag, isValidPrivateKey, loadSphere, logger, mnemonicToEntropy, mnemonicToSeed, mnemonicToSeedSync, privateKeyToAddressInfo, publicKeyToAddress, randomBytes, randomHex, randomUUID, ripemd160, scanAddressesImpl, serializeEncrypted, sha256, sleep, sphereExists, toHumanReadable, toSmallestUnit, validateMnemonic };