@unicitylabs/sphere-sdk 0.5.3 → 0.5.5

package/dist/impl/browser/ipfs.cjs

@@ -538,6 +538,20 @@ var sha256 = /* @__PURE__ */ createHasher(
 var bip39 = __toESM(require("bip39"), 1);
 var import_crypto_js = __toESM(require("crypto-js"), 1);
 var import_elliptic = __toESM(require("elliptic"), 1);
+
+// 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/crypto.ts
 var ec = new import_elliptic.default.ec("secp256k1");
 var CURVE_ORDER = BigInt(
   "0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFEBAAEDCE6AF48A03BBFD25E8CD0364141"
@@ -771,6 +785,98 @@ var IpfsCache = class {
   }
 };
 
+// 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];
+  }
+};
+
 // impl/shared/ipfs/ipfs-http-client.ts
 var DEFAULT_CONNECTIVITY_TIMEOUT_MS = 5e3;
 var DEFAULT_FETCH_TIMEOUT_MS = 15e3;
@@ -927,7 +1033,10 @@ var IpfsHttpClient = class {
           { headers: { Accept: "application/octet-stream" } }
         );
         if (!response.ok) {
-          const body = await response.text().catch(() => "");
+          const body = await response.text().catch((err) => {
+            logger.debug("IPFS-HTTP", "Failed to read error response body", err);
+            return "";
+          });
           throw new IpfsError(
             `Fetch failed: HTTP ${response.status}`,
             classifyHttpStatus(response.status, body),
@@ -973,7 +1082,10 @@ var IpfsHttpClient = class {
         { method: "POST" }
       );
       if (!response.ok) {
-        const body = await response.text().catch(() => "");
+        const body = await response.text().catch((err) => {
+          logger.debug("IPFS-HTTP", "Failed to read error response body", err);
+          return "";
+        });
         const category = classifyHttpStatus(response.status, body);
         if (category === "NOT_FOUND") return null;
         throw new IpfsError(`Routing API: HTTP ${response.status}`, category, gateway);
@@ -1019,7 +1131,8 @@ var IpfsHttpClient = class {
         }
       }
       return { cid: "", content };
-    } catch {
+    } catch (err) {
+      logger.debug("IPFS-HTTP", "IPNS gateway resolution failed", err);
       return null;
     }
   }
@@ -1084,7 +1197,10 @@ var IpfsHttpClient = class {
         { method: "POST", body: formData }
       );
       if (!response.ok) {
-        const errorText = await response.text().catch(() => "");
+        const errorText = await response.text().catch((err) => {
+          logger.debug("IPFS-HTTP", "Failed to read error response body", err);
+          return "";
+        });
         throw new IpfsError(
           `IPNS publish: HTTP ${response.status}: ${errorText.slice(0, 100)}`,
           classifyHttpStatus(response.status, errorText),
@@ -1161,9 +1277,7 @@ var IpfsHttpClient = class {
     }
   }
   log(message) {
-    if (this.debug) {
-      console.log(`[IPFS-HTTP] ${message}`);
-    }
+    logger.debug("IPFS-HTTP", message);
   }
 };
 
@@ -1615,10 +1729,12 @@ var IpnsSubscriptionClient = class {
   startFallbackPolling() {
     if (this.fallbackPollInterval || !this.fallbackPollFn || this.destroyed) return;
     this.log(`Starting fallback polling (${this.fallbackPollIntervalMs / 1e3}s interval)`);
-    this.fallbackPollFn().catch(() => {
+    this.fallbackPollFn().catch((err) => {
+      logger.warn("IPNS-WS", "Fallback poll error:", err);
     });
     this.fallbackPollInterval = setInterval(() => {
-      this.fallbackPollFn?.().catch(() => {
+      this.fallbackPollFn?.().catch((err) => {
+        logger.warn("IPNS-WS", "Fallback poll error:", err);
       });
     }, this.fallbackPollIntervalMs);
   }
@@ -1632,9 +1748,7 @@ var IpnsSubscriptionClient = class {
   // Internal: Logging
   // ---------------------------------------------------------------------------
   log(message) {
-    if (this.debugEnabled) {
-      console.log(`[IPNS-WS] ${message}`);
-    }
+    logger.debug("IPNS-WS", message);
   }
 };
 
@@ -1906,7 +2020,8 @@ var IpfsStorageProvider = class {
         } else {
           this.log("Warning: no healthy gateways found");
         }
-      }).catch(() => {
+      }).catch((err) => {
+        logger.warn("IPFS-Storage", "Gateway health check failed (non-fatal):", err);
       });
       this.isShuttingDown = false;
       this.status = "connected";
@@ -2070,7 +2185,7 @@ var IpfsStorageProvider = class {
       };
       const result = await this._doSave(baseData);
       if (!result.success) {
-        throw new Error(result.error ?? "Save failed");
+        throw new SphereError(result.error ?? "Save failed", "STORAGE_ERROR");
       }
       this.log(`Flushed successfully: CID=${result.cid}`);
     } catch (error) {
@@ -2310,10 +2425,12 @@ var IpfsStorageProvider = class {
     if (this.flushTimer) {
       clearTimeout(this.flushTimer);
       this.flushTimer = null;
-      await this.flushQueue.enqueue(() => this.executeFlush()).catch(() => {
+      await this.flushQueue.enqueue(() => this.executeFlush()).catch((err) => {
+        logger.warn("IPFS-Storage", "Flush on shutdown failed:", err);
       });
     } else if (!this.pendingBuffer.isEmpty) {
-      await this.flushQueue.enqueue(() => this.executeFlush()).catch(() => {
+      await this.flushQueue.enqueue(() => this.executeFlush()).catch((err) => {
+        logger.warn("IPFS-Storage", "Flush on shutdown failed:", err);
       });
     } else {
       await this.flushQueue.enqueue(async () => {
@@ -2367,9 +2484,7 @@ var IpfsStorageProvider = class {
     }
   }
   log(message) {
-    if (this.debug) {
-      console.log(`[IPFS-Storage] ${message}`);
-    }
+    logger.debug("IPFS-Storage", message);
   }
 };