@gethashd/bytecave-browser 1.0.1

package/src/protocol-handler.ts

@@ -0,0 +1,271 @@
+/**
+ * HashD Protocol Handler
+ * 
+ * Handles hashd:// URLs for loading content from ByteCave network.
+ * Format: hashd://{cid}?type={mimeType}&decrypt={boolean}
+ */
+
+import type { ByteCaveClient } from './client.js';
+
+export interface HashdUrl {
+  protocol: 'hashd:';
+  cid: string;
+  mimeType?: string;
+  decrypt?: boolean;
+  raw: string;
+}
+
+export interface FetchOptions {
+  signal?: AbortSignal;
+  timeout?: number;
+}
+
+export interface FetchResult {
+  data: Uint8Array;
+  mimeType: string;
+  blobUrl: string;
+  cached: boolean;
+}
+
+/**
+ * Parse a hashd:// URL into its components
+ */
+export function parseHashdUrl(url: string): HashdUrl {
+  if (!url.startsWith('hashd://')) {
+    throw new Error(`Invalid hashd:// URL: ${url}`);
+  }
+
+  // Remove protocol
+  const withoutProtocol = url.slice(8); // Remove 'hashd://'
+  
+  // Split CID and query params
+  const [cid, queryString] = withoutProtocol.split('?');
+  
+  if (!cid || cid.length === 0) {
+    throw new Error(`Invalid hashd:// URL: missing CID`);
+  }
+
+  const result: HashdUrl = {
+    protocol: 'hashd:',
+    cid,
+    raw: url
+  };
+
+  // Parse query parameters
+  if (queryString) {
+    const params = new URLSearchParams(queryString);
+    
+    if (params.has('type')) {
+      result.mimeType = params.get('type')!;
+    }
+    
+    if (params.has('decrypt')) {
+      result.decrypt = params.get('decrypt') === 'true';
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Create a hashd:// URL from a CID and options
+ */
+export function createHashdUrl(
+  cid: string, 
+  options?: { mimeType?: string; decrypt?: boolean }
+): string {
+  let url = `hashd://${cid}`;
+  
+  if (options) {
+    const params = new URLSearchParams();
+    
+    if (options.mimeType) {
+      params.set('type', options.mimeType);
+    }
+    
+    if (options.decrypt !== undefined) {
+      params.set('decrypt', String(options.decrypt));
+    }
+    
+    const queryString = params.toString();
+    if (queryString) {
+      url += `?${queryString}`;
+    }
+  }
+  
+  return url;
+}
+
+/**
+ * Blob URL cache to avoid re-fetching content
+ */
+class BlobUrlCache {
+  private cache = new Map<string, { blobUrl: string; mimeType: string; timestamp: number }>();
+  private readonly maxAge = 60 * 60 * 1000; // 1 hour
+
+  set(cid: string, blobUrl: string, mimeType: string): void {
+    this.cache.set(cid, { blobUrl, mimeType, timestamp: Date.now() });
+  }
+
+  get(cid: string): { blobUrl: string; mimeType: string } | null {
+    const entry = this.cache.get(cid);
+    
+    if (!entry) {
+      return null;
+    }
+
+    // Check if expired
+    if (Date.now() - entry.timestamp > this.maxAge) {
+      this.revoke(cid);
+      return null;
+    }
+
+    return { blobUrl: entry.blobUrl, mimeType: entry.mimeType };
+  }
+
+  revoke(cid: string): void {
+    const entry = this.cache.get(cid);
+    if (entry) {
+      URL.revokeObjectURL(entry.blobUrl);
+      this.cache.delete(cid);
+    }
+  }
+
+  clear(): void {
+    for (const entry of this.cache.values()) {
+      URL.revokeObjectURL(entry.blobUrl);
+    }
+    this.cache.clear();
+  }
+
+  size(): number {
+    return this.cache.size;
+  }
+}
+
+// Global cache instance
+const blobCache = new BlobUrlCache();
+
+/**
+ * Detect MIME type from data if not provided
+ */
+function detectMimeType(data: Uint8Array): string {
+  // Check magic bytes for common formats
+  if (data.length < 4) {
+    return 'application/octet-stream';
+  }
+
+  // PNG
+  if (data[0] === 0x89 && data[1] === 0x50 && data[2] === 0x4E && data[3] === 0x47) {
+    return 'image/png';
+  }
+
+  // JPEG
+  if (data[0] === 0xFF && data[1] === 0xD8 && data[2] === 0xFF) {
+    return 'image/jpeg';
+  }
+
+  // GIF
+  if (data[0] === 0x47 && data[1] === 0x49 && data[2] === 0x46) {
+    return 'image/gif';
+  }
+
+  // WebP
+  if (data[0] === 0x52 && data[1] === 0x49 && data[2] === 0x46 && data[3] === 0x46 &&
+      data[8] === 0x57 && data[9] === 0x45 && data[10] === 0x42 && data[11] === 0x50) {
+    return 'image/webp';
+  }
+
+  // MP4
+  if (data.length >= 12 && 
+      data[4] === 0x66 && data[5] === 0x74 && data[6] === 0x79 && data[7] === 0x70) {
+    return 'video/mp4';
+  }
+
+  // Default
+  return 'application/octet-stream';
+}
+
+/**
+ * Fetch content from ByteCave network using hashd:// URL
+ */
+export async function fetchHashdContent(
+  url: string | HashdUrl,
+  client: ByteCaveClient,
+  options?: FetchOptions
+): Promise<FetchResult> {
+  // Parse URL if string
+  const parsed = typeof url === 'string' ? parseHashdUrl(url) : url;
+
+  // Check cache first
+  const cached = blobCache.get(parsed.cid);
+  if (cached) {
+    console.log(`[HashD] Cache hit for CID: ${parsed.cid.slice(0, 16)}...`);
+    return {
+      data: new Uint8Array(), // Don't return data for cached items
+      mimeType: cached.mimeType,
+      blobUrl: cached.blobUrl,
+      cached: true
+    };
+  }
+
+  console.log(`[HashD] Fetching CID: ${parsed.cid.slice(0, 16)}...`);
+
+  // Fetch from ByteCave network
+  const result = await client.retrieve(parsed.cid);
+
+  if (!result.success || !result.data) {
+    throw new Error(result.error || 'Failed to retrieve content');
+  }
+
+  // Determine MIME type
+  const mimeType = parsed.mimeType || detectMimeType(result.data);
+
+  // Create blob URL (copy data to avoid SharedArrayBuffer issues)
+  const dataCopy = new Uint8Array(result.data);
+  const blob = new Blob([dataCopy], { type: mimeType });
+  const blobUrl = URL.createObjectURL(blob);
+
+  // Cache the blob URL
+  blobCache.set(parsed.cid, blobUrl, mimeType);
+
+  console.log(`[HashD] Retrieved and cached CID: ${parsed.cid.slice(0, 16)}... (${mimeType})`);
+
+  return {
+    data: result.data,
+    mimeType,
+    blobUrl,
+    cached: false
+  };
+}
+
+/**
+ * Prefetch content and cache it
+ */
+export async function prefetchHashdContent(
+  url: string | HashdUrl,
+  client: ByteCaveClient
+): Promise<void> {
+  await fetchHashdContent(url, client);
+}
+
+/**
+ * Clear the blob URL cache
+ */
+export function clearHashdCache(): void {
+  blobCache.clear();
+}
+
+/**
+ * Get cache statistics
+ */
+export function getHashdCacheStats(): { size: number } {
+  return { size: blobCache.size() };
+}
+
+/**
+ * Revoke a specific blob URL from cache
+ */
+export function revokeHashdUrl(cid: string): void {
+  blobCache.revoke(cid);
+}

package/src/provider.tsx

@@ -0,0 +1,275 @@
+/**
+ * React Context Provider for ByteCave Client
+ * 
+ * Provides P2P connectivity state and methods to React components
+ */
+
+import React, { createContext, useContext, ReactNode, useState, useEffect, useRef, useCallback } from 'react';
+import { ByteCaveClient } from './client.js';
+import type { ByteCaveConfig, PeerInfo, ConnectionState, StoreResult, RetrieveResult } from './types.js';
+
+interface NodeHealth {
+  status: string;
+  blobCount: number;
+  storageUsed: number;
+  uptime: number;
+  nodeId?: string;
+  publicKey?: string;
+  secp256k1PublicKey?: string;
+  ownerAddress?: string;
+  metrics?: {
+    requestsLastHour: number;
+    avgResponseTime: number;
+    successRate: number;
+  };
+  integrity?: {
+    checked: number;
+    passed: number;
+    failed: number;
+    orphaned: number;
+    metadataTampered: number;
+    failedCids: string[];
+  };
+}
+
+interface ByteCaveContextValue {
+  connectionState: ConnectionState;
+  peers: PeerInfo[];
+  isConnected: boolean;
+  appId: string;
+  connect: () => Promise<void>;
+  disconnect: () => Promise<void>;
+  store: (data: Uint8Array, mimeType?: string, signer?: any) => Promise<StoreResult>;
+  retrieve: (cid: string) => Promise<RetrieveResult>;
+  registerContent: (cid: string, appId: string, signer: any) => Promise<{ success: boolean; txHash?: string; error?: string }>;
+  getNodeHealth: (peerId: string) => Promise<NodeHealth | null>;
+  error: string | null;
+}
+
+const ByteCaveContext = createContext<ByteCaveContextValue | null>(null);
+
+interface ByteCaveProviderProps {
+  children: ReactNode;
+  vaultNodeRegistryAddress: string;
+  contentRegistryAddress?: string;
+  rpcUrl: string;
+  appId: string;
+  relayPeers?: string[];
+  directNodeAddrs?: string[];
+}
+
+let globalClient: ByteCaveClient | null = null;
+
+export function ByteCaveProvider({ 
+  children, 
+  vaultNodeRegistryAddress,
+  contentRegistryAddress,
+  rpcUrl,
+  appId,
+  relayPeers = [],
+  directNodeAddrs = []
+}: ByteCaveProviderProps) {
+  const [connectionState, setConnectionState] = useState<ConnectionState>('disconnected');
+  const [peers, setPeers] = useState<PeerInfo[]>([]);
+  const [error, setError] = useState<string | null>(null);
+  const connectCalledRef = useRef(false);
+
+  const connect = useCallback(async () => {
+    if (!globalClient) {
+      setError('ByteCave client not initialized');
+      return;
+    }
+
+    try {
+      const currentState = globalClient.getConnectionState();
+      if (currentState !== 'connected') {
+        await globalClient.start();
+      }
+      
+      const actualState = globalClient.getConnectionState();
+      const peers = await globalClient.getPeers();
+      
+      setConnectionState(actualState);
+      setPeers(peers);
+    } catch (err: any) {
+      setError(err.message);
+      setConnectionState('error');
+    }
+  }, []);
+
+  useEffect(() => {
+    if (!vaultNodeRegistryAddress) {
+      return;
+    }
+
+    const initializeClient = async () => {
+      // Don't reinitialize if client already exists
+      if (globalClient) {
+        console.log('[ByteCaveProvider] Client already exists, skipping initialization');
+        return;
+      }
+      
+      console.log('[ByteCaveProvider] Creating new ByteCaveClient');
+      globalClient = new ByteCaveClient({
+        vaultNodeRegistryAddress,
+        contentRegistryAddress,
+        rpcUrl,
+        appId,
+        directNodeAddrs,
+        relayPeers,
+        maxPeers: 10,
+        connectionTimeout: 30000
+      });
+
+      const client = globalClient;
+
+      const handleStateChange = (state: ConnectionState) => {
+        setConnectionState(state);
+      };
+      
+      const handlePeerUpdate = async () => {
+        if (!client) return;
+        try {
+          const peers = await client.getPeers();
+          setPeers(peers);
+        } catch (err) {
+          // Silent
+        }
+      };
+
+      client.on('connectionStateChange', handleStateChange);
+      client.on('peerConnect', handlePeerUpdate);
+      client.on('peerDisconnect', handlePeerUpdate);
+
+      const hasPeers = directNodeAddrs.length > 0 || relayPeers.length > 0;
+      
+      console.log('[ByteCaveProvider] Auto-connect check:', {
+        hasPeers,
+        directNodeAddrs: directNodeAddrs.length,
+        relayPeers: relayPeers.length,
+        connectCalled: connectCalledRef.current
+      });
+      
+      if (hasPeers && !connectCalledRef.current) {
+        connectCalledRef.current = true;
+        console.log('[ByteCaveProvider] Auto-connecting in 100ms...');
+        setTimeout(() => {
+          console.log('[ByteCaveProvider] Calling connect()...');
+          connect();
+        }, 100);
+      } else if (!hasPeers) {
+        console.warn('[ByteCaveProvider] No relay peers or direct node addresses configured - cannot auto-connect');
+      }
+    };
+
+    initializeClient();
+
+    return () => {
+      if (globalClient) {
+        globalClient.off('connectionStateChange', () => {});
+        globalClient.off('peerConnect', () => {});
+        globalClient.off('peerDisconnect', () => {});
+      }
+    };
+  }, []); // Empty deps - only initialize once on mount
+
+  // Auto-reconnect when peers drop to 0
+  useEffect(() => {
+    const reconnectInterval = setInterval(async () => {
+      if (peers.length === 0 && connectionState === 'connected' && globalClient) {
+        console.log('[ByteCaveProvider] No peers connected, attempting reconnection...');
+        try {
+          await connect();
+        } catch (err) {
+          console.error('[ByteCaveProvider] Reconnection failed:', err);
+        }
+      }
+    }, 5000);
+
+    return () => clearInterval(reconnectInterval);
+  }, [peers.length, connectionState, connect]);
+
+  // Periodic peer directory refresh to rediscover nodes
+  useEffect(() => {
+    const refreshInterval = setInterval(async () => {
+      if (connectionState === 'connected' && globalClient) {
+        console.log('[ByteCaveProvider] Refreshing peer directory...');
+        try {
+          await globalClient.refreshPeerDirectory();
+          const updatedPeers = await globalClient.getPeers();
+          setPeers(updatedPeers);
+        } catch (err) {
+          console.error('[ByteCaveProvider] Peer directory refresh failed:', err);
+        }
+      }
+    }, 30000); // Refresh every 30 seconds
+
+    return () => clearInterval(refreshInterval);
+  }, [connectionState]);
+
+  const disconnect = async () => {
+    if (!globalClient) return;
+    try {
+      await globalClient.stop();
+      setPeers([]);
+    } catch (err: any) {
+      setError(err.message);
+    }
+  };
+
+  const store = async (data: Uint8Array, mimeType?: string, signer?: any): Promise<StoreResult> => {
+    if (!globalClient) {
+      return { success: false, error: 'Client not initialized' };
+    }
+    return (globalClient as any).store(data, mimeType, signer);
+  };
+
+  const retrieve = async (cid: string): Promise<RetrieveResult> => {
+    if (!globalClient) {
+      return { success: false, error: 'Client not initialized' };
+    }
+    return globalClient.retrieve(cid);
+  };
+
+  const getNodeHealth = async (peerId: string): Promise<NodeHealth | null> => {
+    if (!globalClient) {
+      return null;
+    }
+    return (globalClient as any).getNodeHealth(peerId);
+  };
+
+  const registerContent = async (cid: string, appId: string, signer: any): Promise<{ success: boolean; txHash?: string; error?: string }> => {
+    if (!globalClient) {
+      return { success: false, error: 'Client not initialized' };
+    }
+    return globalClient.registerContent(cid, appId, signer);
+  };
+
+  const value: ByteCaveContextValue = {
+    connectionState,
+    peers,
+    isConnected: connectionState === 'connected',
+    appId,
+    connect,
+    disconnect,
+    store,
+    retrieve,
+    registerContent,
+    getNodeHealth,
+    error
+  };
+
+  return (
+    <ByteCaveContext.Provider value={value}>
+      {children}
+    </ByteCaveContext.Provider>
+  );
+}
+
+export function useByteCaveContext() {
+  const context = useContext(ByteCaveContext);
+  if (!context) {
+    throw new Error('useByteCaveContext must be used within ByteCaveProvider');
+  }
+  return context;
+}

package/src/react/components.tsx

@@ -0,0 +1,177 @@
+/**
+ * React Components for HashD Protocol
+ * 
+ * Drop-in components for loading content from ByteCave network
+ */
+
+import React, { ImgHTMLAttributes, VideoHTMLAttributes, AudioHTMLAttributes } from 'react';
+import { useHashdImage, useHashdMedia, type UseHashdContentOptions } from './hooks.js';
+
+export interface HashdImageProps extends Omit<ImgHTMLAttributes<HTMLImageElement>, 'src'> {
+  src: string;
+  client: UseHashdContentOptions['client'];
+  placeholder?: string;
+  loadingComponent?: React.ReactNode;
+  errorComponent?: React.ReactNode;
+  onHashdLoad?: () => void;
+  onHashdError?: (error: Error) => void;
+}
+
+/**
+ * Drop-in replacement for <img> that loads from hashd:// URLs
+ * 
+ * @example
+ * <HashdImage 
+ *   src="hashd://abc123..." 
+ *   client={byteCaveClient}
+ *   alt="Profile picture"
+ *   className="w-32 h-32 rounded-full"
+ * />
+ */
+export function HashdImage({
+  src,
+  client,
+  placeholder,
+  loadingComponent,
+  errorComponent,
+  onHashdLoad,
+  onHashdError,
+  ...imgProps
+}: HashdImageProps) {
+  const { src: blobUrl, loading, error } = useHashdImage(src, {
+    client,
+    placeholder,
+    onSuccess: onHashdLoad,
+    onError: onHashdError
+  });
+
+  if (loading && loadingComponent) {
+    return <>{loadingComponent}</>;
+  }
+
+  if (error && errorComponent) {
+    return <>{errorComponent}</>;
+  }
+
+  return <img {...imgProps} src={blobUrl} />;
+}
+
+export interface HashdVideoProps extends Omit<VideoHTMLAttributes<HTMLVideoElement>, 'src'> {
+  src: string;
+  client: UseHashdContentOptions['client'];
+  loadingComponent?: React.ReactNode;
+  errorComponent?: React.ReactNode;
+  onHashdLoad?: () => void;
+  onHashdError?: (error: Error) => void;
+}
+
+/**
+ * Drop-in replacement for <video> that loads from hashd:// URLs
+ * 
+ * @example
+ * <HashdVideo 
+ *   src="hashd://abc123..." 
+ *   client={byteCaveClient}
+ *   controls
+ *   className="w-full"
+ * />
+ */
+export function HashdVideo({
+  src,
+  client,
+  loadingComponent,
+  errorComponent,
+  onHashdLoad,
+  onHashdError,
+  ...videoProps
+}: HashdVideoProps) {
+  const { src: blobUrl, loading, error } = useHashdMedia(src, {
+    client,
+    onSuccess: onHashdLoad,
+    onError: onHashdError
+  });
+
+  if (loading && loadingComponent) {
+    return <>{loadingComponent}</>;
+  }
+
+  if (error && errorComponent) {
+    return <>{errorComponent}</>;
+  }
+
+  return <video {...videoProps} src={blobUrl} />;
+}
+
+export interface HashdAudioProps extends Omit<AudioHTMLAttributes<HTMLAudioElement>, 'src'> {
+  src: string;
+  client: UseHashdContentOptions['client'];
+  loadingComponent?: React.ReactNode;
+  errorComponent?: React.ReactNode;
+  onHashdLoad?: () => void;
+  onHashdError?: (error: Error) => void;
+}
+
+/**
+ * Drop-in replacement for <audio> that loads from hashd:// URLs
+ * 
+ * @example
+ * <HashdAudio 
+ *   src="hashd://abc123..." 
+ *   client={byteCaveClient}
+ *   controls
+ * />
+ */
+export function HashdAudio({
+  src,
+  client,
+  loadingComponent,
+  errorComponent,
+  onHashdLoad,
+  onHashdError,
+  ...audioProps
+}: HashdAudioProps) {
+  const { src: blobUrl, loading, error } = useHashdMedia(src, {
+    client,
+    onSuccess: onHashdLoad,
+    onError: onHashdError
+  });
+
+  if (loading && loadingComponent) {
+    return <>{loadingComponent}</>;
+  }
+
+  if (error && errorComponent) {
+    return <>{errorComponent}</>;
+  }
+
+  return <audio {...audioProps} src={blobUrl} />;
+}
+
+export interface HashdContentProps {
+  url: string;
+  client: UseHashdContentOptions['client'];
+  children: (props: {
+    blobUrl: string | null;
+    loading: boolean;
+    error: Error | null;
+    mimeType: string | null;
+  }) => React.ReactNode;
+}
+
+/**
+ * Render prop component for custom content rendering
+ * 
+ * @example
+ * <HashdContent url="hashd://abc123..." client={client}>
+ *   {({ blobUrl, loading, error }) => {
+ *     if (loading) return <Spinner />;
+ *     if (error) return <Error message={error.message} />;
+ *     return <img src={blobUrl} />;
+ *   }}
+ * </HashdContent>
+ */
+export function HashdContent({ url, client, children }: HashdContentProps) {
+  const { blobUrl, loading, error, mimeType } = useHashdImage(url, { client });
+
+  return <>{children({ blobUrl, loading, error, mimeType })}</>;
+}