@unicitylabs/sphere-sdk 0.5.4 → 0.5.5

package/dist/l1/index.js

@@ -23,6 +23,18 @@ function domIdToPath(encoded) {
   }).join("/");
 }
 
+// core/errors.ts
+var SphereError = class extends Error {
+  code;
+  cause;
+  constructor(message, code, cause) {
+    super(message);
+    this.name = "SphereError";
+    this.code = code;
+    this.cause = cause;
+  }
+};
+
 // core/bech32.ts
 var CHARSET = "qpzry9x8gf2tvdw0s3jn54khce6mua7l";
 var GENERATOR = [996825010, 642813549, 513874426, 1027748829, 705979059];
@@ -79,11 +91,11 @@ function bech32Checksum(hrp, data) {
 }
 function encodeBech32(hrp, version, program) {
   if (version < 0 || version > 16) {
-    throw new Error("Invalid witness version");
+    throw new SphereError("Invalid witness version", "VALIDATION_ERROR");
   }
   const converted = convertBits(Array.from(program), 8, 5, true);
   if (!converted) {
-    throw new Error("Failed to convert bits");
+    throw new SphereError("Failed to convert bits", "VALIDATION_ERROR");
   }
   const data = [version].concat(converted);
   const checksum = bech32Checksum(hrp, data);
@@ -130,7 +142,7 @@ function bytesToHex(buf) {
 }
 function addressToScriptHash(address) {
   const decoded = decodeBech32(address);
-  if (!decoded) throw new Error("Invalid bech32 address: " + address);
+  if (!decoded) throw new SphereError("Invalid bech32 address: " + address, "VALIDATION_ERROR");
   const scriptHex = "0014" + bytesToHex(decoded.data);
   const sha = CryptoJS.SHA256(CryptoJS.enc.Hex.parse(scriptHex)).toString();
   return sha.match(/../g).reverse().join("");
@@ -153,7 +165,7 @@ function generateMasterKey(seedHex) {
   const IR = I.substring(64);
   const masterKeyBigInt = BigInt("0x" + IL);
   if (masterKeyBigInt === 0n || masterKeyBigInt >= CURVE_ORDER) {
-    throw new Error("Invalid master key generated");
+    throw new SphereError("Invalid master key generated", "VALIDATION_ERROR");
   }
   return {
     privateKey: IL,
@@ -181,11 +193,11 @@ function deriveChildKey(parentPrivKey, parentChainCode, index) {
   const ilBigInt = BigInt("0x" + IL);
   const parentKeyBigInt = BigInt("0x" + parentPrivKey);
   if (ilBigInt >= CURVE_ORDER) {
-    throw new Error("Invalid key: IL >= curve order");
+    throw new SphereError("Invalid key: IL >= curve order", "VALIDATION_ERROR");
   }
   const childKeyBigInt = (ilBigInt + parentKeyBigInt) % CURVE_ORDER;
   if (childKeyBigInt === 0n) {
-    throw new Error("Invalid key: child key is zero");
+    throw new SphereError("Invalid key: child key is zero", "VALIDATION_ERROR");
   }
   const childPrivKey = childKeyBigInt.toString(16).padStart(64, "0");
   return {
@@ -355,6 +367,98 @@ function generateHDAddress(masterPriv, chainCode, index) {
   return generateAddressInfo(child.privateKey, index, path);
 }
 
+// core/logger.ts
+var LOGGER_KEY = "__sphere_sdk_logger__";
+function getState() {
+  const g = globalThis;
+  if (!g[LOGGER_KEY]) {
+    g[LOGGER_KEY] = { debug: false, tags: {}, handler: null };
+  }
+  return g[LOGGER_KEY];
+}
+function isEnabled(tag) {
+  const state = getState();
+  if (tag in state.tags) return state.tags[tag];
+  return state.debug;
+}
+var logger = {
+  /**
+   * Configure the logger. Can be called multiple times (last write wins).
+   * Typically called by createBrowserProviders(), createNodeProviders(), or Sphere.init().
+   */
+  configure(config) {
+    const state = getState();
+    if (config.debug !== void 0) state.debug = config.debug;
+    if (config.handler !== void 0) state.handler = config.handler;
+  },
+  /**
+   * 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, enabled) {
+    getState().tags[tag] = enabled;
+  },
+  /**
+   * Clear per-tag override, falling back to global debug flag.
+   */
+  clearTagDebug(tag) {
+    delete getState().tags[tag];
+  },
+  /** Returns true if debug mode is enabled for the given tag (or globally). */
+  isDebugEnabled(tag) {
+    if (tag) return isEnabled(tag);
+    return getState().debug;
+  },
+  /**
+   * Debug-level log. Only shown when debug is enabled (globally or for this tag).
+   * Use for detailed operational information.
+   */
+  debug(tag, message, ...args) {
+    if (!isEnabled(tag)) return;
+    const state = getState();
+    if (state.handler) {
+      state.handler("debug", tag, message, ...args);
+    } else {
+      console.log(`[${tag}]`, message, ...args);
+    }
+  },
+  /**
+   * Warning-level log. ALWAYS shown regardless of debug flag.
+   * Use for important but non-critical issues (timeouts, retries, degraded state).
+   */
+  warn(tag, message, ...args) {
+    const state = getState();
+    if (state.handler) {
+      state.handler("warn", tag, message, ...args);
+    } else {
+      console.warn(`[${tag}]`, message, ...args);
+    }
+  },
+  /**
+   * Error-level log. ALWAYS shown regardless of debug flag.
+   * Use for critical failures that should never be silenced.
+   */
+  error(tag, message, ...args) {
+    const state = getState();
+    if (state.handler) {
+      state.handler("error", tag, message, ...args);
+    } else {
+      console.error(`[${tag}]`, message, ...args);
+    }
+  },
+  /** Reset all logger state (debug flag, tags, handler). Primarily for tests. */
+  reset() {
+    const g = globalThis;
+    delete g[LOGGER_KEY];
+  }
+};
+
 // constants.ts
 var STORAGE_KEYS_GLOBAL = {
   /** Encrypted BIP39 mnemonic */
@@ -483,7 +587,7 @@ function connect(endpoint = DEFAULT_ENDPOINT) {
     try {
       ws = new WebSocket(endpoint);
     } catch (err) {
-      console.error("[L1] WebSocket constructor threw exception:", err);
+      logger.error("L1", "WebSocket constructor threw exception:", err);
       isConnecting = false;
       reject(err);
       return;
@@ -519,7 +623,7 @@ function connect(endpoint = DEFAULT_ENDPOINT) {
         return;
       }
       if (reconnectAttempts >= MAX_RECONNECT_ATTEMPTS) {
-        console.error("[L1] Max reconnect attempts reached. Giving up.");
+        logger.error("L1", "Max reconnect attempts reached. Giving up.");
         isConnecting = false;
         const error = new Error("Max reconnect attempts reached");
         connectionCallbacks.forEach((cb) => {
@@ -535,8 +639,9 @@ function connect(endpoint = DEFAULT_ENDPOINT) {
       }
       const delay = Math.min(BASE_DELAY * Math.pow(2, reconnectAttempts), MAX_DELAY);
       reconnectAttempts++;
-      console.warn(
-        `[L1] WebSocket closed unexpectedly. Reconnecting in ${delay}ms (attempt ${reconnectAttempts}/${MAX_RECONNECT_ATTEMPTS})...`
+      logger.warn(
+        "L1",
+        `WebSocket closed unexpectedly. Reconnecting in ${delay}ms (attempt ${reconnectAttempts}/${MAX_RECONNECT_ATTEMPTS})...`
       );
       setTimeout(() => {
         connect(endpoint).then(() => {
@@ -553,7 +658,7 @@ function connect(endpoint = DEFAULT_ENDPOINT) {
       }, delay);
     };
     ws.onerror = (err) => {
-      console.error("[L1] WebSocket error:", err);
+      logger.error("L1", "WebSocket error:", err);
     };
     ws.onmessage = (msg) => handleMessage(msg);
   });
@@ -611,7 +716,7 @@ async function getUtxo(address) {
   const scripthash = addressToScriptHash(address);
   const result = await rpc("blockchain.scripthash.listunspent", [scripthash]);
   if (!Array.isArray(result)) {
-    console.warn("listunspent returned non-array:", result);
+    logger.warn("L1", "listunspent returned non-array:", result);
     return [];
   }
   return result.map((u) => ({
@@ -663,7 +768,7 @@ async function getTransactionHistory(address) {
   const scriptHash = addressToScriptHash(address);
   const result = await rpc("blockchain.scripthash.get_history", [scriptHash]);
   if (!Array.isArray(result)) {
-    console.warn("get_history returned non-array:", result);
+    logger.warn("L1", "get_history returned non-array:", result);
     return [];
   }
   return result;
@@ -679,7 +784,7 @@ async function getCurrentBlockHeight() {
     const header = await rpc("blockchain.headers.subscribe", []);
     return header?.height || 0;
   } catch (err) {
-    console.error("Error getting current block height:", err);
+    logger.error("L1", "Error getting current block height:", err);
     return 0;
   }
 }
@@ -951,7 +1056,7 @@ var VestingClassifier = class {
       await new Promise((resolve) => {
         const req = indexedDB.deleteDatabase(this.dbName);
         const timer = setTimeout(() => {
-          console.warn(`[VestingClassifier] destroy: deleteDatabase timed out for ${this.dbName}`);
+          logger.warn("L1", ` destroy: deleteDatabase timed out for ${this.dbName}`);
           resolve();
         }, 3e3);
         req.onsuccess = () => {
@@ -963,7 +1068,7 @@ var VestingClassifier = class {
           resolve();
         };
         req.onblocked = () => {
-          console.warn(`[VestingClassifier] destroy: deleteDatabase blocked for ${this.dbName}, waiting...`);
+          logger.warn("L1", ` destroy: deleteDatabase blocked for ${this.dbName}, waiting...`);
         };
       });
     }
@@ -981,7 +1086,7 @@ var VestingStateManager = class {
    */
   setMode(mode) {
     if (!["all", "vested", "unvested"].includes(mode)) {
-      throw new Error(`Invalid vesting mode: ${mode}`);
+      throw new SphereError(`Invalid vesting mode: ${mode}`, "VALIDATION_ERROR");
     }
     this.currentMode = mode;
   }
@@ -1018,10 +1123,10 @@ var VestingStateManager = class {
         }
       });
       if (result.errors.length > 0) {
-        console.warn(`Vesting classification errors: ${result.errors.length}`);
+        logger.warn("L1", `Vesting classification errors: ${result.errors.length}`);
         result.errors.slice(0, 5).forEach((err) => {
           const txHash = err.utxo.tx_hash || err.utxo.txid;
-          console.warn(`  ${txHash}: ${err.error}`);
+          logger.warn("L1", `  ${txHash}: ${err.error}`);
         });
       }
     } finally {
@@ -1143,16 +1248,17 @@ var WalletAddressHelper = class {
    */
   static add(wallet, newAddress) {
     if (!newAddress.path) {
-      throw new Error("Cannot add address without a path");
+      throw new SphereError("Cannot add address without a path", "INVALID_CONFIG");
     }
     const existing = this.findByPath(wallet, newAddress.path);
     if (existing) {
       if (existing.address !== newAddress.address) {
-        throw new Error(
+        throw new SphereError(
           `CRITICAL: Attempted to overwrite address for path ${newAddress.path}
 Existing: ${existing.address}
 New: ${newAddress.address}
-This indicates master key corruption or derivation logic error.`
+This indicates master key corruption or derivation logic error.`,
+          "INVALID_CONFIG"
         );
       }
       return wallet;
@@ -1211,9 +1317,10 @@ This indicates master key corruption or derivation logic error.`
     const uniquePaths = new Set(paths);
     if (paths.length !== uniquePaths.size) {
       const duplicates = paths.filter((p, i) => paths.indexOf(p) !== i);
-      throw new Error(
+      throw new SphereError(
         `CRITICAL: Wallet has duplicate paths: ${duplicates.join(", ")}
-This indicates data corruption. Please restore from backup.`
+This indicates data corruption. Please restore from backup.`,
+        "INVALID_CONFIG"
       );
     }
   }
@@ -1245,11 +1352,11 @@ var DUST = 546;
 var SAT = 1e8;
 function createScriptPubKey(address) {
   if (!address || typeof address !== "string") {
-    throw new Error("Invalid address: must be a string");
+    throw new SphereError("Invalid address: must be a string", "VALIDATION_ERROR");
   }
   const decoded = decodeBech32(address);
   if (!decoded) {
-    throw new Error("Invalid bech32 address: " + address);
+    throw new SphereError("Invalid bech32 address: " + address, "VALIDATION_ERROR");
   }
   const dataHex = Array.from(decoded.data).map((byte) => byte.toString(16).padStart(2, "0")).join("");
   return "0014" + dataHex;
@@ -1373,7 +1480,7 @@ function createAndSignTransaction(wallet, txPlan) {
     privateKeyHex = wallet.masterPrivateKey;
   }
   if (!privateKeyHex) {
-    throw new Error("No private key available for address: " + fromAddress);
+    throw new SphereError("No private key available for address: " + fromAddress, "INVALID_CONFIG");
   }
   const keyPair = ec2.keyFromPrivate(privateKeyHex, "hex");
   const publicKey = keyPair.getPublic(true, "hex");
@@ -1472,7 +1579,7 @@ function collectUtxosForAmount(utxoList, amountSats, recipientAddress, senderAdd
 }
 async function createTransactionPlan(wallet, toAddress, amountAlpha, fromAddress) {
   if (!decodeBech32(toAddress)) {
-    throw new Error("Invalid recipient address");
+    throw new SphereError("Invalid recipient address", "INVALID_RECIPIENT");
   }
   const defaultAddr = WalletAddressHelper.getDefault(wallet);
   const senderAddress = fromAddress || defaultAddr.address;
@@ -1481,21 +1588,21 @@ async function createTransactionPlan(wallet, toAddress, amountAlpha, fromAddress
   const currentMode = vestingState.getMode();
   if (vestingState.hasClassifiedData(senderAddress)) {
     utxos = vestingState.getFilteredUtxos(senderAddress);
-    console.log(`Using ${utxos.length} ${currentMode} UTXOs`);
+    logger.debug("L1", `Using ${utxos.length} ${currentMode} UTXOs`);
   } else {
     utxos = await getUtxo(senderAddress);
-    console.log(`Using ${utxos.length} UTXOs (vesting not classified yet)`);
+    logger.debug("L1", `Using ${utxos.length} UTXOs (vesting not classified yet)`);
   }
   if (!Array.isArray(utxos) || utxos.length === 0) {
     const modeText = currentMode !== "all" ? ` (${currentMode} coins)` : "";
-    throw new Error(`No UTXOs available${modeText} for address: ` + senderAddress);
+    throw new SphereError(`No UTXOs available${modeText} for address: ` + senderAddress, "INSUFFICIENT_BALANCE");
   }
   return collectUtxosForAmount(utxos, amountSats, toAddress, senderAddress);
 }
 async function sendAlpha(wallet, toAddress, amountAlpha, fromAddress) {
   const plan = await createTransactionPlan(wallet, toAddress, amountAlpha, fromAddress);
   if (!plan.success) {
-    throw new Error(plan.error || "Transaction planning failed");
+    throw new SphereError(plan.error || "Transaction planning failed", "TRANSFER_FAILED");
   }
   const results = [];
   for (const tx of plan.transactions) {