@gethashd/bytecave-browser 1.0.1

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * ByteCave Browser Client
+ *
+ * WebRTC P2P client for connecting browsers directly to ByteCave storage nodes.
+ * No central gateway required - fully decentralized.
+ */
+export declare const TEST_EXPORT = "ByteCave Browser Package v1.0.0";
+export { ByteCaveClient } from './client.js';
+export { ContractDiscovery } from './discovery.js';
+export { p2pProtocolClient } from './p2p-protocols.js';
+export { ByteCaveProvider, useByteCaveContext } from './provider.js';
+export type { P2PHealthResponse, P2PInfoResponse } from './p2p-protocols.js';
+export type { ByteCaveConfig, PeerInfo, StoreResult, RetrieveResult, ConnectionState } from './types.js';
+export { parseHashdUrl, createHashdUrl, fetchHashdContent, prefetchHashdContent, clearHashdCache, getHashdCacheStats, revokeHashdUrl } from './protocol-handler.js';
+export type { HashdUrl, FetchOptions, FetchResult } from './protocol-handler.js';
+export { useHashdContent, useHashdImage, useHashdMedia, useHashdBatch } from './react/hooks.js';
+export { HashdImage, HashdVideo, HashdAudio } from './react/components.js';
+export { useHashdUrl } from './react/useHashdUrl.js';

package/dist/index.js

@@ -0,0 +1,50 @@
+import {
+  ByteCaveClient,
+  ByteCaveProvider,
+  ContractDiscovery,
+  HashdAudio,
+  HashdImage,
+  HashdVideo,
+  p2pProtocolClient,
+  useByteCaveContext,
+  useHashdBatch,
+  useHashdContent,
+  useHashdImage,
+  useHashdMedia,
+  useHashdUrl
+} from "./chunk-OJEETLZQ.js";
+import {
+  clearHashdCache,
+  createHashdUrl,
+  fetchHashdContent,
+  getHashdCacheStats,
+  parseHashdUrl,
+  prefetchHashdContent,
+  revokeHashdUrl
+} from "./chunk-EEZWRIUI.js";
+
+// src/index.ts
+var TEST_EXPORT = "ByteCave Browser Package v1.0.0";
+export {
+  ByteCaveClient,
+  ByteCaveProvider,
+  ContractDiscovery,
+  HashdAudio,
+  HashdImage,
+  HashdVideo,
+  TEST_EXPORT,
+  clearHashdCache,
+  createHashdUrl,
+  fetchHashdContent,
+  getHashdCacheStats,
+  p2pProtocolClient,
+  parseHashdUrl,
+  prefetchHashdContent,
+  revokeHashdUrl,
+  useByteCaveContext,
+  useHashdBatch,
+  useHashdContent,
+  useHashdImage,
+  useHashdMedia,
+  useHashdUrl
+};

package/dist/p2p-protocols.d.ts

@@ -0,0 +1,114 @@
+/**
+ * ByteCave Browser - P2P Protocol Client
+ *
+ * Implements libp2p stream protocols for pure P2P communication from browser:
+ * - /bytecave/blob/1.0.0 - Blob storage and retrieval
+ * - /bytecave/health/1.0.0 - Health status
+ * - /bytecave/info/1.0.0 - Node info (for registration)
+ */
+import { Libp2p } from 'libp2p';
+export declare const PROTOCOL_BLOB = "/bytecave/blob/1.0.0";
+export declare const PROTOCOL_HEALTH = "/bytecave/health/1.0.0";
+export declare const PROTOCOL_INFO = "/bytecave/info/1.0.0";
+export declare const PROTOCOL_PEER_DIRECTORY = "/bytecave/relay/peers/1.0.0";
+export declare const PROTOCOL_HAVE_LIST = "/bytecave/have-list/1.0.0";
+export interface BlobResponse {
+    success: boolean;
+    ciphertext?: string;
+    mimeType?: string;
+    error?: string;
+}
+export interface P2PHealthResponse {
+    peerId: string;
+    status: 'healthy' | 'degraded' | 'unhealthy';
+    blobCount: number;
+    storageUsed: number;
+    storageMax: number;
+    uptime: number;
+    version: string;
+    multiaddrs: string[];
+    nodeId?: string;
+    publicKey?: string;
+    ownerAddress?: string;
+    contentTypes?: string[] | 'all';
+    metrics?: {
+        requestsLastHour: number;
+        avgResponseTime: number;
+        successRate: number;
+    };
+}
+export interface P2PInfoResponse {
+    peerId: string;
+    publicKey: string;
+    ownerAddress?: string;
+    version: string;
+    contentTypes: string[] | 'all';
+}
+export interface PeerDirectoryResponse {
+    peers: Array<{
+        peerId: string;
+        multiaddrs: string[];
+        lastSeen: number;
+    }>;
+    timestamp: number;
+}
+export interface HaveListResponse {
+    cids: string[];
+    total: number;
+    hasMore: boolean;
+}
+export interface StoreRequest {
+    cid: string;
+    mimeType: string;
+    ciphertext: string;
+    appId?: string;
+    shouldVerifyOnChain?: boolean;
+    sender?: string;
+    timestamp?: number;
+    metadata?: Record<string, any>;
+    authorization?: any;
+}
+export interface StoreResponse {
+    success: boolean;
+    cid?: string;
+    error?: string;
+}
+/**
+ * P2P Protocol client for browser-to-node communication
+ */
+export declare class P2PProtocolClient {
+    private node;
+    setNode(node: Libp2p): void;
+    /**
+     * Store a blob on a peer via P2P stream
+     */
+    storeToPeer(peerId: string, ciphertext: Uint8Array, mimeType: string, authorization?: any, shouldVerifyOnChain?: boolean): Promise<StoreResponse>;
+    /**
+     * Retrieve a blob from a peer via P2P stream
+     */
+    retrieveFromPeer(peerId: string, cid: string): Promise<{
+        data: Uint8Array;
+        mimeType: string;
+    } | null>;
+    /**
+     * Get health info from a peer via P2P stream
+     */
+    getHealthFromPeer(peerId: string): Promise<P2PHealthResponse | null>;
+    /**
+     * Query relay for peer directory
+     */
+    getPeerDirectoryFromRelay(relayPeerId: string): Promise<PeerDirectoryResponse | null>;
+    /**
+     * Get node info from a peer via P2P stream (for registration)
+     */
+    getInfoFromPeer(peerId: string): Promise<P2PInfoResponse | null>;
+    /**
+     * Check if a peer has a specific CID
+     */
+    peerHasCid(peerId: string, cid: string): Promise<boolean>;
+    private readMessage;
+    private writeMessage;
+    private uint8ArrayToBase64;
+    private base64ToUint8Array;
+}
+export declare const p2pProtocolClient: P2PProtocolClient;

package/dist/protocol-handler.cjs

@@ -0,0 +1,185 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/protocol-handler.ts
+var protocol_handler_exports = {};
+__export(protocol_handler_exports, {
+  clearHashdCache: () => clearHashdCache,
+  createHashdUrl: () => createHashdUrl,
+  fetchHashdContent: () => fetchHashdContent,
+  getHashdCacheStats: () => getHashdCacheStats,
+  parseHashdUrl: () => parseHashdUrl,
+  prefetchHashdContent: () => prefetchHashdContent,
+  revokeHashdUrl: () => revokeHashdUrl
+});
+module.exports = __toCommonJS(protocol_handler_exports);
+function parseHashdUrl(url) {
+  if (!url.startsWith("hashd://")) {
+    throw new Error(`Invalid hashd:// URL: ${url}`);
+  }
+  const withoutProtocol = url.slice(8);
+  const [cid, queryString] = withoutProtocol.split("?");
+  if (!cid || cid.length === 0) {
+    throw new Error(`Invalid hashd:// URL: missing CID`);
+  }
+  const result = {
+    protocol: "hashd:",
+    cid,
+    raw: url
+  };
+  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;
+}
+function createHashdUrl(cid, options) {
+  let url = `hashd://${cid}`;
+  if (options) {
+    const params = new URLSearchParams();
+    if (options.mimeType) {
+      params.set("type", options.mimeType);
+    }
+    if (options.decrypt !== void 0) {
+      params.set("decrypt", String(options.decrypt));
+    }
+    const queryString = params.toString();
+    if (queryString) {
+      url += `?${queryString}`;
+    }
+  }
+  return url;
+}
+var BlobUrlCache = class {
+  constructor() {
+    this.cache = /* @__PURE__ */ new Map();
+    this.maxAge = 60 * 60 * 1e3;
+  }
+  // 1 hour
+  set(cid, blobUrl, mimeType) {
+    this.cache.set(cid, { blobUrl, mimeType, timestamp: Date.now() });
+  }
+  get(cid) {
+    const entry = this.cache.get(cid);
+    if (!entry) {
+      return null;
+    }
+    if (Date.now() - entry.timestamp > this.maxAge) {
+      this.revoke(cid);
+      return null;
+    }
+    return { blobUrl: entry.blobUrl, mimeType: entry.mimeType };
+  }
+  revoke(cid) {
+    const entry = this.cache.get(cid);
+    if (entry) {
+      URL.revokeObjectURL(entry.blobUrl);
+      this.cache.delete(cid);
+    }
+  }
+  clear() {
+    for (const entry of this.cache.values()) {
+      URL.revokeObjectURL(entry.blobUrl);
+    }
+    this.cache.clear();
+  }
+  size() {
+    return this.cache.size;
+  }
+};
+var blobCache = new BlobUrlCache();
+function detectMimeType(data) {
+  if (data.length < 4) {
+    return "application/octet-stream";
+  }
+  if (data[0] === 137 && data[1] === 80 && data[2] === 78 && data[3] === 71) {
+    return "image/png";
+  }
+  if (data[0] === 255 && data[1] === 216 && data[2] === 255) {
+    return "image/jpeg";
+  }
+  if (data[0] === 71 && data[1] === 73 && data[2] === 70) {
+    return "image/gif";
+  }
+  if (data[0] === 82 && data[1] === 73 && data[2] === 70 && data[3] === 70 && data[8] === 87 && data[9] === 69 && data[10] === 66 && data[11] === 80) {
+    return "image/webp";
+  }
+  if (data.length >= 12 && data[4] === 102 && data[5] === 116 && data[6] === 121 && data[7] === 112) {
+    return "video/mp4";
+  }
+  return "application/octet-stream";
+}
+async function fetchHashdContent(url, client, options) {
+  const parsed = typeof url === "string" ? parseHashdUrl(url) : url;
+  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)}...`);
+  const result = await client.retrieve(parsed.cid);
+  if (!result.success || !result.data) {
+    throw new Error(result.error || "Failed to retrieve content");
+  }
+  const mimeType = parsed.mimeType || detectMimeType(result.data);
+  const dataCopy = new Uint8Array(result.data);
+  const blob = new Blob([dataCopy], { type: mimeType });
+  const blobUrl = URL.createObjectURL(blob);
+  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
+  };
+}
+async function prefetchHashdContent(url, client) {
+  await fetchHashdContent(url, client);
+}
+function clearHashdCache() {
+  blobCache.clear();
+}
+function getHashdCacheStats() {
+  return { size: blobCache.size() };
+}
+function revokeHashdUrl(cid) {
+  blobCache.revoke(cid);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  clearHashdCache,
+  createHashdUrl,
+  fetchHashdContent,
+  getHashdCacheStats,
+  parseHashdUrl,
+  prefetchHashdContent,
+  revokeHashdUrl
+});

package/dist/protocol-handler.d.ts

@@ -0,0 +1,57 @@
+/**
+ * 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 declare function parseHashdUrl(url: string): HashdUrl;
+/**
+ * Create a hashd:// URL from a CID and options
+ */
+export declare function createHashdUrl(cid: string, options?: {
+    mimeType?: string;
+    decrypt?: boolean;
+}): string;
+/**
+ * Fetch content from ByteCave network using hashd:// URL
+ */
+export declare function fetchHashdContent(url: string | HashdUrl, client: ByteCaveClient, options?: FetchOptions): Promise<FetchResult>;
+/**
+ * Prefetch content and cache it
+ */
+export declare function prefetchHashdContent(url: string | HashdUrl, client: ByteCaveClient): Promise<void>;
+/**
+ * Clear the blob URL cache
+ */
+export declare function clearHashdCache(): void;
+/**
+ * Get cache statistics
+ */
+export declare function getHashdCacheStats(): {
+    size: number;
+};
+/**
+ * Revoke a specific blob URL from cache
+ */
+export declare function revokeHashdUrl(cid: string): void;

package/dist/protocol-handler.js

@@ -0,0 +1,18 @@
+import {
+  clearHashdCache,
+  createHashdUrl,
+  fetchHashdContent,
+  getHashdCacheStats,
+  parseHashdUrl,
+  prefetchHashdContent,
+  revokeHashdUrl
+} from "./chunk-EEZWRIUI.js";
+export {
+  clearHashdCache,
+  createHashdUrl,
+  fetchHashdContent,
+  getHashdCacheStats,
+  parseHashdUrl,
+  prefetchHashdContent,
+  revokeHashdUrl
+};

package/dist/provider.d.ts

@@ -0,0 +1,59 @@
+/**
+ * React Context Provider for ByteCave Client
+ *
+ * Provides P2P connectivity state and methods to React components
+ */
+import React, { ReactNode } from 'react';
+import type { 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;
+}
+interface ByteCaveProviderProps {
+    children: ReactNode;
+    vaultNodeRegistryAddress: string;
+    contentRegistryAddress?: string;
+    rpcUrl: string;
+    appId: string;
+    relayPeers?: string[];
+    directNodeAddrs?: string[];
+}
+export declare function ByteCaveProvider({ children, vaultNodeRegistryAddress, contentRegistryAddress, rpcUrl, appId, relayPeers, directNodeAddrs }: ByteCaveProviderProps): React.JSX.Element;
+export declare function useByteCaveContext(): ByteCaveContextValue;
+export {};

package/dist/react/components.d.ts

@@ -0,0 +1,90 @@
+/**
+ * React Components for HashD Protocol
+ *
+ * Drop-in components for loading content from ByteCave network
+ */
+import React, { ImgHTMLAttributes, VideoHTMLAttributes, AudioHTMLAttributes } from 'react';
+import { 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 declare function HashdImage({ src, client, placeholder, loadingComponent, errorComponent, onHashdLoad, onHashdError, ...imgProps }: HashdImageProps): React.JSX.Element;
+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 declare function HashdVideo({ src, client, loadingComponent, errorComponent, onHashdLoad, onHashdError, ...videoProps }: HashdVideoProps): React.JSX.Element;
+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 declare function HashdAudio({ src, client, loadingComponent, errorComponent, onHashdLoad, onHashdError, ...audioProps }: HashdAudioProps): React.JSX.Element;
+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 declare function HashdContent({ url, client, children }: HashdContentProps): React.JSX.Element;

package/dist/react/hooks.d.ts

@@ -0,0 +1,67 @@
+/**
+ * React Hooks for HASHD Protocol
+ *
+ * Provides hooks for loading content from ByteCave network using hashd:// URLs
+ */
+import type { ByteCaveClient } from '../client.js';
+export interface UseHashdContentOptions {
+    client: ByteCaveClient | null;
+    enabled?: boolean;
+    onSuccess?: (blobUrl: string) => void;
+    onError?: (error: Error) => void;
+}
+export interface UseHashdContentResult {
+    blobUrl: string | null;
+    data: Uint8Array | null;
+    mimeType: string | null;
+    loading: boolean;
+    error: Error | null;
+    cached: boolean;
+    refetch: () => void;
+}
+/**
+ * Hook for loading content from hashd:// URLs
+ *
+ * @example
+ * const { blobUrl, loading, error } = useHashdContent('hashd://abc123...', { client });
+ * if (loading) return <Spinner />;
+ * if (error) return <Error message={error.message} />;
+ * return <img src={blobUrl} />;
+ */
+export declare function useHashdContent(url: string | null | undefined, options: UseHashdContentOptions): UseHashdContentResult;
+/**
+ * Hook specifically for loading images from hashd:// URLs
+ * Includes image-specific optimizations and error handling
+ *
+ * @example
+ * const { src, loading, error } = useHashdImage('hashd://abc123...', { client });
+ * return <img src={src || placeholderImage} alt="..." />;
+ */
+export declare function useHashdImage(url: string | null | undefined, options: UseHashdContentOptions & {
+    placeholder?: string;
+}): UseHashdContentResult & {
+    src: string;
+};
+/**
+ * Hook for loading video/audio content from hashd:// URLs
+ * Optimized for media playback
+ *
+ * @example
+ * const { src, loading } = useHashdMedia('hashd://abc123...', { client });
+ * return <video src={src} controls />;
+ */
+export declare function useHashdMedia(url: string | null | undefined, options: UseHashdContentOptions): UseHashdContentResult & {
+    src: string;
+};
+/**
+ * Hook for batch loading multiple hashd:// URLs
+ * Useful for galleries or lists
+ *
+ * @example
+ * const { results, loading, errors } = useHashdBatch(urls, { client });
+ */
+export declare function useHashdBatch(urls: (string | null | undefined)[], options: UseHashdContentOptions): {
+    results: Map<string, UseHashdContentResult>;
+    loading: boolean;
+    errors: Map<string, Error>;
+};