@gethashd/bytecave-browser 1.0.29 → 1.0.31

package/dist/{chunk-CTI3NP4T.js → chunk-LPLEL6EN.js}

@@ -6067,6 +6067,105 @@ import { multiaddr } from "@multiformats/multiaddr";
 import { fromString, toString } from "uint8arrays";
 import { ethers as ethers2 } from "ethers";
 
+// src/storage-websocket.ts
+var StorageWebSocketClient = class {
+  constructor(relayUrl) {
+    this.relayUrl = relayUrl;
+    this.ws = null;
+    this.pendingRequests = /* @__PURE__ */ new Map();
+  }
+  async connect() {
+    if (this.ws && this.ws.readyState === WebSocket.OPEN) {
+      return;
+    }
+    return new Promise((resolve, reject) => {
+      this.ws = new WebSocket(this.relayUrl);
+      this.ws.onopen = () => {
+        console.log("[Storage WS] Connected to relay");
+        resolve();
+      };
+      this.ws.onmessage = (event) => {
+        try {
+          const message2 = JSON.parse(event.data);
+          this.handleMessage(message2);
+        } catch (error) {
+          console.error("[Storage WS] Failed to parse message:", error.message);
+        }
+      };
+      this.ws.onerror = (error) => {
+        console.error("[Storage WS] WebSocket error:", error);
+        reject(new Error("WebSocket connection failed"));
+      };
+      this.ws.onclose = () => {
+        console.log("[Storage WS] Connection closed");
+        this.ws = null;
+        for (const [requestId, pending] of this.pendingRequests.entries()) {
+          clearTimeout(pending.timeout);
+          pending.reject(new Error("WebSocket connection closed"));
+        }
+        this.pendingRequests.clear();
+      };
+    });
+  }
+  handleMessage(message2) {
+    if (message2.type === "storage-response") {
+      const pending = this.pendingRequests.get(message2.requestId);
+      if (pending) {
+        clearTimeout(pending.timeout);
+        this.pendingRequests.delete(message2.requestId);
+        if (message2.success && message2.cid) {
+          pending.resolve({ success: true, cid: message2.cid });
+        } else {
+          pending.resolve({ success: false, error: message2.error || "Storage failed" });
+        }
+      }
+    }
+  }
+  async store(options) {
+    if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+      await this.connect();
+    }
+    const requestId = Math.random().toString(36).substring(2, 15) + Math.random().toString(36).substring(2, 15);
+    const base64Data = btoa(String.fromCharCode(...options.data));
+    const request = {
+      type: "storage-request",
+      requestId,
+      data: base64Data,
+      contentType: options.contentType,
+      authorization: options.authorization
+    };
+    return new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        this.pendingRequests.delete(requestId);
+        reject(new Error("Storage request timeout"));
+      }, options.timeout || 3e4);
+      this.pendingRequests.set(requestId, { resolve, reject, timeout });
+      try {
+        this.ws.send(JSON.stringify(request));
+        console.log("[Storage WS] Sent storage request:", requestId);
+      } catch (error) {
+        clearTimeout(timeout);
+        this.pendingRequests.delete(requestId);
+        reject(error);
+      }
+    });
+  }
+  disconnect() {
+    if (this.ws) {
+      this.ws.close();
+      this.ws = null;
+    }
+    for (const [requestId, pending] of this.pendingRequests.entries()) {
+      clearTimeout(pending.timeout);
+      pending.reject(new Error("Client disconnected"));
+    }
+    this.pendingRequests.clear();
+  }
+  isConnected() {
+    return this.ws !== null && this.ws.readyState === WebSocket.OPEN;
+  }
+};
+
 // src/contracts/ContentRegistry.ts
 var CONTENT_REGISTRY_ABI = [
   "function registerContent(bytes32 cid, address owner, bytes32 appId) external",
@@ -6449,6 +6548,38 @@ Nonce: ${nonce}`;
         console.warn("[ByteCave] Failed to create authorization:", err.message);
       }
     }
+    if (this.config.relayWsUrl) {
+      console.log("[ByteCave] Attempting WebSocket storage via relay");
+      try {
+        if (!this.storageWsClient) {
+          this.storageWsClient = new StorageWebSocketClient(this.config.relayWsUrl);
+        }
+        const wsAuth = authorization ? {
+          signature: authorization.signature,
+          address: authorization.sender,
+          timestamp: authorization.timestamp,
+          nonce: authorization.nonce
+        } : void 0;
+        const result = await this.storageWsClient.store({
+          data: dataArray,
+          contentType: mimeType || "application/octet-stream",
+          authorization: wsAuth,
+          timeout: 3e4
+        });
+        if (result.success && result.cid) {
+          console.log("[ByteCave] \u2713 WebSocket storage successful:", result.cid);
+          return {
+            success: true,
+            cid: result.cid,
+            peerId: "relay-ws"
+          };
+        }
+        console.warn("[ByteCave] WebSocket storage failed:", result.error);
+      } catch (err) {
+        console.warn("[ByteCave] WebSocket storage exception:", err.message);
+      }
+    }
+    console.log("[ByteCave] Falling back to P2P storage");
     const errors = [];
     for (const peerId of storagePeerIds) {
       console.log("[ByteCave] Attempting P2P store to peer:", peerId.slice(0, 12) + "...");
@@ -6478,8 +6609,8 @@ Nonce: ${nonce}`;
         errors.push(errorMsg);
       }
     }
-    console.error("[ByteCave] All storage peers failed. Errors:", errors);
-    return { success: false, error: `All storage peers failed: ${errors.join("; ")}` };
+    console.error("[ByteCave] All storage methods failed. Errors:", errors);
+    return { success: false, error: `All storage methods failed: ${errors.join("; ")}` };
   }
   /**
    * Retrieve ciphertext from a node via P2P only (no HTTP fallback)
@@ -6647,16 +6778,9 @@ Nonce: ${nonce}`;
       const peerInfo = this.knownPeers.get(peerId);
       const relayAddrs = peerInfo?.relayAddrs;
       if (relayAddrs && relayAddrs.length > 0 && this.node) {
-        const webrtcRelayAddrs = relayAddrs.filter((addr) => addr.includes("/webrtc"));
-        const plainRelayAddrs = relayAddrs.filter((addr) => !addr.includes("/webrtc"));
-        const addrToUse = webrtcRelayAddrs.length > 0 ? webrtcRelayAddrs[0] : plainRelayAddrs[0];
-        console.log("[ByteCave] Dialing peer through relay:", peerId.slice(0, 12), {
-          webrtcAvailable: webrtcRelayAddrs.length,
-          plainAvailable: plainRelayAddrs.length,
-          using: addrToUse
-        });
+        console.log("[ByteCave] Dialing peer through relay:", peerId.slice(0, 12), relayAddrs[0]);
         try {
-          const ma = multiaddr(addrToUse);
+          const ma = multiaddr(relayAddrs[0]);
           await this.node.dial(ma);
           console.log("[ByteCave] Successfully dialed peer through relay");
         } catch (dialError) {
@@ -6836,6 +6960,7 @@ function ByteCaveProvider({
   appId,
   relayPeers = [],
   relayHttpUrl,
+  relayWsUrl,
   directNodeAddrs = []
 }) {
   const [connectionState, setConnectionState] = useState("disconnected");
@@ -6879,6 +7004,7 @@ function ByteCaveProvider({
         directNodeAddrs,
         relayPeers,
         relayHttpUrl,
+        relayWsUrl,
         maxPeers: 10,
         connectionTimeout: 3e4
       });

package/dist/client.d.ts

@@ -9,6 +9,7 @@ export declare class ByteCaveClient {
     private node;
     private contractDiscovery?;
     private relayDiscovery?;
+    private storageWsClient?;
     private config;
     private knownPeers;
     private connectionState;

package/dist/index.cjs

@@ -6120,6 +6120,105 @@ var P2PProtocolClient = class {
 };
 var p2pProtocolClient = new P2PProtocolClient();
 
+// src/storage-websocket.ts
+var StorageWebSocketClient = class {
+  constructor(relayUrl) {
+    this.relayUrl = relayUrl;
+    this.ws = null;
+    this.pendingRequests = /* @__PURE__ */ new Map();
+  }
+  async connect() {
+    if (this.ws && this.ws.readyState === WebSocket.OPEN) {
+      return;
+    }
+    return new Promise((resolve, reject) => {
+      this.ws = new WebSocket(this.relayUrl);
+      this.ws.onopen = () => {
+        console.log("[Storage WS] Connected to relay");
+        resolve();
+      };
+      this.ws.onmessage = (event) => {
+        try {
+          const message2 = JSON.parse(event.data);
+          this.handleMessage(message2);
+        } catch (error) {
+          console.error("[Storage WS] Failed to parse message:", error.message);
+        }
+      };
+      this.ws.onerror = (error) => {
+        console.error("[Storage WS] WebSocket error:", error);
+        reject(new Error("WebSocket connection failed"));
+      };
+      this.ws.onclose = () => {
+        console.log("[Storage WS] Connection closed");
+        this.ws = null;
+        for (const [requestId, pending] of this.pendingRequests.entries()) {
+          clearTimeout(pending.timeout);
+          pending.reject(new Error("WebSocket connection closed"));
+        }
+        this.pendingRequests.clear();
+      };
+    });
+  }
+  handleMessage(message2) {
+    if (message2.type === "storage-response") {
+      const pending = this.pendingRequests.get(message2.requestId);
+      if (pending) {
+        clearTimeout(pending.timeout);
+        this.pendingRequests.delete(message2.requestId);
+        if (message2.success && message2.cid) {
+          pending.resolve({ success: true, cid: message2.cid });
+        } else {
+          pending.resolve({ success: false, error: message2.error || "Storage failed" });
+        }
+      }
+    }
+  }
+  async store(options) {
+    if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+      await this.connect();
+    }
+    const requestId = Math.random().toString(36).substring(2, 15) + Math.random().toString(36).substring(2, 15);
+    const base64Data = btoa(String.fromCharCode(...options.data));
+    const request = {
+      type: "storage-request",
+      requestId,
+      data: base64Data,
+      contentType: options.contentType,
+      authorization: options.authorization
+    };
+    return new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        this.pendingRequests.delete(requestId);
+        reject(new Error("Storage request timeout"));
+      }, options.timeout || 3e4);
+      this.pendingRequests.set(requestId, { resolve, reject, timeout });
+      try {
+        this.ws.send(JSON.stringify(request));
+        console.log("[Storage WS] Sent storage request:", requestId);
+      } catch (error) {
+        clearTimeout(timeout);
+        this.pendingRequests.delete(requestId);
+        reject(error);
+      }
+    });
+  }
+  disconnect() {
+    if (this.ws) {
+      this.ws.close();
+      this.ws = null;
+    }
+    for (const [requestId, pending] of this.pendingRequests.entries()) {
+      clearTimeout(pending.timeout);
+      pending.reject(new Error("Client disconnected"));
+    }
+    this.pendingRequests.clear();
+  }
+  isConnected() {
+    return this.ws !== null && this.ws.readyState === WebSocket.OPEN;
+  }
+};
+
 // src/contracts/ContentRegistry.ts
 var CONTENT_REGISTRY_ABI = [
   "function registerContent(bytes32 cid, address owner, bytes32 appId) external",
@@ -6502,6 +6601,38 @@ Nonce: ${nonce}`;
         console.warn("[ByteCave] Failed to create authorization:", err.message);
       }
     }
+    if (this.config.relayWsUrl) {
+      console.log("[ByteCave] Attempting WebSocket storage via relay");
+      try {
+        if (!this.storageWsClient) {
+          this.storageWsClient = new StorageWebSocketClient(this.config.relayWsUrl);
+        }
+        const wsAuth = authorization ? {
+          signature: authorization.signature,
+          address: authorization.sender,
+          timestamp: authorization.timestamp,
+          nonce: authorization.nonce
+        } : void 0;
+        const result = await this.storageWsClient.store({
+          data: dataArray,
+          contentType: mimeType || "application/octet-stream",
+          authorization: wsAuth,
+          timeout: 3e4
+        });
+        if (result.success && result.cid) {
+          console.log("[ByteCave] \u2713 WebSocket storage successful:", result.cid);
+          return {
+            success: true,
+            cid: result.cid,
+            peerId: "relay-ws"
+          };
+        }
+        console.warn("[ByteCave] WebSocket storage failed:", result.error);
+      } catch (err) {
+        console.warn("[ByteCave] WebSocket storage exception:", err.message);
+      }
+    }
+    console.log("[ByteCave] Falling back to P2P storage");
     const errors = [];
     for (const peerId of storagePeerIds) {
       console.log("[ByteCave] Attempting P2P store to peer:", peerId.slice(0, 12) + "...");
@@ -6531,8 +6662,8 @@ Nonce: ${nonce}`;
         errors.push(errorMsg);
       }
     }
-    console.error("[ByteCave] All storage peers failed. Errors:", errors);
-    return { success: false, error: `All storage peers failed: ${errors.join("; ")}` };
+    console.error("[ByteCave] All storage methods failed. Errors:", errors);
+    return { success: false, error: `All storage methods failed: ${errors.join("; ")}` };
   }
   /**
    * Retrieve ciphertext from a node via P2P only (no HTTP fallback)
@@ -6700,16 +6831,9 @@ Nonce: ${nonce}`;
       const peerInfo = this.knownPeers.get(peerId);
       const relayAddrs = peerInfo?.relayAddrs;
       if (relayAddrs && relayAddrs.length > 0 && this.node) {
-        const webrtcRelayAddrs = relayAddrs.filter((addr) => addr.includes("/webrtc"));
-        const plainRelayAddrs = relayAddrs.filter((addr) => !addr.includes("/webrtc"));
-        const addrToUse = webrtcRelayAddrs.length > 0 ? webrtcRelayAddrs[0] : plainRelayAddrs[0];
-        console.log("[ByteCave] Dialing peer through relay:", peerId.slice(0, 12), {
-          webrtcAvailable: webrtcRelayAddrs.length,
-          plainAvailable: plainRelayAddrs.length,
-          using: addrToUse
-        });
+        console.log("[ByteCave] Dialing peer through relay:", peerId.slice(0, 12), relayAddrs[0]);
         try {
-          const ma = (0, import_multiaddr.multiaddr)(addrToUse);
+          const ma = (0, import_multiaddr.multiaddr)(relayAddrs[0]);
           await this.node.dial(ma);
           console.log("[ByteCave] Successfully dialed peer through relay");
         } catch (dialError) {
@@ -6889,6 +7013,7 @@ function ByteCaveProvider({
   appId,
   relayPeers = [],
   relayHttpUrl,
+  relayWsUrl,
   directNodeAddrs = []
 }) {
   const [connectionState, setConnectionState] = (0, import_react.useState)("disconnected");
@@ -6932,6 +7057,7 @@ function ByteCaveProvider({
         directNodeAddrs,
         relayPeers,
         relayHttpUrl,
+        relayWsUrl,
         maxPeers: 10,
         connectionTimeout: 3e4
       });

package/dist/index.js

@@ -13,7 +13,7 @@ import {
   useHashdImage,
   useHashdMedia,
   useHashdUrl
-} from "./chunk-CTI3NP4T.js";
+} from "./chunk-LPLEL6EN.js";
 import {
   clearHashdCache,
   createHashdUrl,

package/dist/provider.d.ts

@@ -53,8 +53,9 @@ interface ByteCaveProviderProps {
     appId: string;
     relayPeers?: string[];
     relayHttpUrl?: string;
+    relayWsUrl?: string;
     directNodeAddrs?: string[];
 }
-export declare function ByteCaveProvider({ children, vaultNodeRegistryAddress, contentRegistryAddress, rpcUrl, appId, relayPeers, relayHttpUrl, directNodeAddrs }: ByteCaveProviderProps): React.JSX.Element;
+export declare function ByteCaveProvider({ children, vaultNodeRegistryAddress, contentRegistryAddress, rpcUrl, appId, relayPeers, relayHttpUrl, relayWsUrl, directNodeAddrs }: ByteCaveProviderProps): React.JSX.Element;
 export declare function useByteCaveContext(): ByteCaveContextValue;
 export {};

package/dist/react/index.js

@@ -8,7 +8,7 @@ import {
   useHashdImage,
   useHashdMedia,
   useHashdUrl
-} from "../chunk-CTI3NP4T.js";
+} from "../chunk-LPLEL6EN.js";
 import "../chunk-EEZWRIUI.js";
 export {
   HashdAudio,

package/dist/storage-websocket.d.ts

@@ -0,0 +1,30 @@
+/**
+ * WebSocket Storage Client for Browser
+ * Sends storage requests to relay, which routes to storage nodes
+ */
+export interface StoreViaWebSocketOptions {
+    data: Uint8Array;
+    contentType: string;
+    authorization?: {
+        signature: string;
+        address: string;
+        timestamp: number;
+        nonce: string;
+    };
+    timeout?: number;
+}
+export declare class StorageWebSocketClient {
+    private relayUrl;
+    private ws;
+    private pendingRequests;
+    constructor(relayUrl: string);
+    connect(): Promise<void>;
+    private handleMessage;
+    store(options: StoreViaWebSocketOptions): Promise<{
+        success: boolean;
+        cid?: string;
+        error?: string;
+    }>;
+    disconnect(): void;
+    isConnected(): boolean;
+}

package/dist/types.d.ts

@@ -9,6 +9,7 @@ export interface ByteCaveConfig {
     directNodeAddrs?: string[];
     relayPeers?: string[];
     relayHttpUrl?: string;
+    relayWsUrl?: string;
     maxPeers?: number;
     connectionTimeout?: number;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gethashd/bytecave-browser",
-  "version": "1.0.29",
+  "version": "1.0.31",
   "description": "ByteCave browser client for WebRTC P2P connections to storage nodes",
   "main": "dist/index.cjs",
   "module": "dist/index.js",

package/src/client.ts

@@ -20,6 +20,7 @@ import { fromString, toString } from 'uint8arrays';
 import { ethers } from 'ethers';
 import { ContractDiscovery, RelayDiscovery } from './discovery.js';
 import { p2pProtocolClient } from './p2p-protocols.js';
+import { StorageWebSocketClient } from './storage-websocket.js';
 import { CONTENT_REGISTRY_ABI } from './contracts/ContentRegistry.js';
 import type { 
   ByteCaveConfig, 
@@ -37,6 +38,7 @@ export class ByteCaveClient {
   private node: Libp2p | null = null;
   private contractDiscovery?: ContractDiscovery; // Optional - only if contract address provided
   private relayDiscovery?: RelayDiscovery; // Optional - for fast peer discovery via relay
+  private storageWsClient?: StorageWebSocketClient; // Optional - for WebSocket storage via relay
   private config: ByteCaveConfig;
   private knownPeers: Map<string, PeerInfo> = new Map();
   private connectionState: ConnectionState = 'disconnected';
@@ -499,7 +501,46 @@ Nonce: ${nonce}`;
       }
     }
 
-    // Try each storage peer until one succeeds
+    // Try WebSocket storage first if relay WS URL is configured
+    if (this.config.relayWsUrl) {
+      console.log('[ByteCave] Attempting WebSocket storage via relay');
+      
+      try {
+        if (!this.storageWsClient) {
+          this.storageWsClient = new StorageWebSocketClient(this.config.relayWsUrl);
+        }
+
+        const wsAuth = authorization ? {
+          signature: authorization.signature,
+          address: authorization.sender,
+          timestamp: authorization.timestamp,
+          nonce: authorization.nonce
+        } : undefined;
+
+        const result = await this.storageWsClient.store({
+          data: dataArray,
+          contentType: mimeType || 'application/octet-stream',
+          authorization: wsAuth,
+          timeout: 30000
+        });
+
+        if (result.success && result.cid) {
+          console.log('[ByteCave] ✓ WebSocket storage successful:', result.cid);
+          return {
+            success: true,
+            cid: result.cid,
+            peerId: 'relay-ws'
+          };
+        }
+
+        console.warn('[ByteCave] WebSocket storage failed:', result.error);
+      } catch (err: any) {
+        console.warn('[ByteCave] WebSocket storage exception:', err.message);
+      }
+    }
+
+    // Fallback to P2P storage
+    console.log('[ByteCave] Falling back to P2P storage');
     const errors: string[] = [];
     for (const peerId of storagePeerIds) {
       console.log('[ByteCave] Attempting P2P store to peer:', peerId.slice(0, 12) + '...');
@@ -532,8 +573,8 @@ Nonce: ${nonce}`;
       }
     }
     
-    console.error('[ByteCave] All storage peers failed. Errors:', errors);
-    return { success: false, error: `All storage peers failed: ${errors.join('; ')}` };
+    console.error('[ByteCave] All storage methods failed. Errors:', errors);
+    return { success: false, error: `All storage methods failed: ${errors.join('; ')}` };
   }
 
   /**
@@ -750,20 +791,10 @@ Nonce: ${nonce}`;
       const relayAddrs = (peerInfo as any)?.relayAddrs;
       
       // If we have relay addresses, dial through relay first
-      // Prefer WebRTC circuit relay addresses for direct connections
       if (relayAddrs && relayAddrs.length > 0 && this.node) {
-        const webrtcRelayAddrs = relayAddrs.filter((addr: string) => addr.includes('/webrtc'));
-        const plainRelayAddrs = relayAddrs.filter((addr: string) => !addr.includes('/webrtc'));
-        const addrToUse = webrtcRelayAddrs.length > 0 ? webrtcRelayAddrs[0] : plainRelayAddrs[0];
-        
-        console.log('[ByteCave] Dialing peer through relay:', peerId.slice(0, 12), {
-          webrtcAvailable: webrtcRelayAddrs.length,
-          plainAvailable: plainRelayAddrs.length,
-          using: addrToUse
-        });
-        
+        console.log('[ByteCave] Dialing peer through relay:', peerId.slice(0, 12), relayAddrs[0]);
         try {
-          const ma = multiaddr(addrToUse);
+          const ma = multiaddr(relayAddrs[0]);
           await this.node.dial(ma as any);
           console.log('[ByteCave] Successfully dialed peer through relay');
         } catch (dialError) {

package/src/provider.tsx

@@ -56,6 +56,7 @@ interface ByteCaveProviderProps {
   appId: string;
   relayPeers?: string[];
   relayHttpUrl?: string;
+  relayWsUrl?: string;
   directNodeAddrs?: string[];
 }
 
@@ -69,6 +70,7 @@ export function ByteCaveProvider({
   appId,
   relayPeers = [],
   relayHttpUrl,
+  relayWsUrl,
   directNodeAddrs = []
 }: ByteCaveProviderProps) {
   const [connectionState, setConnectionState] = useState<ConnectionState>('disconnected');
@@ -120,6 +122,7 @@ export function ByteCaveProvider({
         directNodeAddrs,
         relayPeers,
         relayHttpUrl,
+        relayWsUrl,
         maxPeers: 10,
         connectionTimeout: 30000
       });

package/src/storage-websocket.ts

@@ -0,0 +1,162 @@
+/**
+ * WebSocket Storage Client for Browser
+ * Sends storage requests to relay, which routes to storage nodes
+ */
+
+interface StorageRequestMessage {
+  type: 'storage-request';
+  requestId: string;
+  data: string; // base64
+  contentType: string;
+  authorization?: {
+    signature: string;
+    address: string;
+    timestamp: number;
+    nonce: string;
+  };
+}
+
+interface StorageResponseMessage {
+  type: 'storage-response';
+  requestId: string;
+  success: boolean;
+  cid?: string;
+  error?: string;
+}
+
+type Message = StorageRequestMessage | StorageResponseMessage;
+
+export interface StoreViaWebSocketOptions {
+  data: Uint8Array;
+  contentType: string;
+  authorization?: {
+    signature: string;
+    address: string;
+    timestamp: number;
+    nonce: string;
+  };
+  timeout?: number;
+}
+
+export class StorageWebSocketClient {
+  private ws: WebSocket | null = null;
+  private pendingRequests: Map<string, {
+    resolve: (result: { success: boolean; cid?: string; error?: string }) => void;
+    reject: (error: Error) => void;
+    timeout: NodeJS.Timeout;
+  }> = new Map();
+
+  constructor(private relayUrl: string) {}
+
+  async connect(): Promise<void> {
+    if (this.ws && this.ws.readyState === WebSocket.OPEN) {
+      return;
+    }
+
+    return new Promise((resolve, reject) => {
+      this.ws = new WebSocket(this.relayUrl);
+
+      this.ws.onopen = () => {
+        console.log('[Storage WS] Connected to relay');
+        resolve();
+      };
+
+      this.ws.onmessage = (event) => {
+        try {
+          const message = JSON.parse(event.data) as Message;
+          this.handleMessage(message);
+        } catch (error: any) {
+          console.error('[Storage WS] Failed to parse message:', error.message);
+        }
+      };
+
+      this.ws.onerror = (error) => {
+        console.error('[Storage WS] WebSocket error:', error);
+        reject(new Error('WebSocket connection failed'));
+      };
+
+      this.ws.onclose = () => {
+        console.log('[Storage WS] Connection closed');
+        this.ws = null;
+        // Reject all pending requests
+        for (const [requestId, pending] of this.pendingRequests.entries()) {
+          clearTimeout(pending.timeout);
+          pending.reject(new Error('WebSocket connection closed'));
+        }
+        this.pendingRequests.clear();
+      };
+    });
+  }
+
+  private handleMessage(message: Message): void {
+    if (message.type === 'storage-response') {
+      const pending = this.pendingRequests.get(message.requestId);
+      if (pending) {
+        clearTimeout(pending.timeout);
+        this.pendingRequests.delete(message.requestId);
+        
+        if (message.success && message.cid) {
+          pending.resolve({ success: true, cid: message.cid });
+        } else {
+          pending.resolve({ success: false, error: message.error || 'Storage failed' });
+        }
+      }
+    }
+  }
+
+  async store(options: StoreViaWebSocketOptions): Promise<{ success: boolean; cid?: string; error?: string }> {
+    if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+      await this.connect();
+    }
+
+    const requestId = Math.random().toString(36).substring(2, 15) + 
+                      Math.random().toString(36).substring(2, 15);
+
+    // Convert Uint8Array to base64
+    const base64Data = btoa(String.fromCharCode(...options.data));
+
+    const request: StorageRequestMessage = {
+      type: 'storage-request',
+      requestId,
+      data: base64Data,
+      contentType: options.contentType,
+      authorization: options.authorization
+    };
+
+    return new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        this.pendingRequests.delete(requestId);
+        reject(new Error('Storage request timeout'));
+      }, options.timeout || 30000);
+
+      this.pendingRequests.set(requestId, { resolve, reject, timeout });
+
+      try {
+        this.ws!.send(JSON.stringify(request));
+        console.log('[Storage WS] Sent storage request:', requestId);
+      } catch (error: any) {
+        clearTimeout(timeout);
+        this.pendingRequests.delete(requestId);
+        reject(error);
+      }
+    });
+  }
+
+  disconnect(): void {
+    if (this.ws) {
+      this.ws.close();
+      this.ws = null;
+    }
+    
+    // Clear all pending requests
+    for (const [requestId, pending] of this.pendingRequests.entries()) {
+      clearTimeout(pending.timeout);
+      pending.reject(new Error('Client disconnected'));
+    }
+    this.pendingRequests.clear();
+  }
+
+  isConnected(): boolean {
+    return this.ws !== null && this.ws.readyState === WebSocket.OPEN;
+  }
+}

package/src/types.ts

@@ -10,6 +10,7 @@ export interface ByteCaveConfig {
   directNodeAddrs?: string[]; // Direct node multiaddrs for WebRTC connections (no relay)
   relayPeers?: string[]; // Relay node multiaddrs for circuit relay (e.g., /ip4/127.0.0.1/tcp/4002/ws/p2p/...)
   relayHttpUrl?: string; // Optional - Relay HTTP URL for instant peer discovery (e.g., http://localhost:9090)
+  relayWsUrl?: string; // Optional - Relay WebSocket URL for browser storage (e.g., ws://localhost:4003)
   maxPeers?: number;
   connectionTimeout?: number;
 }