WebHash SDK

A TypeScript SDK for interacting with the Webhash network. Upload files and directories to Webhash public nodes and register them on the chain.

Installation

npm install webhash
# or
yarn add webhash

Usage

import { WebhashClient } from "webhash";
import * as path from "path";

// Replace with your actual private key
const privateKey = "0xYOUR_PRIVATE_KEY";

const client = new WebhashClient(privateKey);

async function uploadMyFile() {
  try {
    const filePath = path.resolve(__dirname, "path/to/your/file.txt"); // Use absolute path
    // Optionally specify an uploader address (must be a valid address string)
    // const uploader = "0xYourUploaderAddress";
    const result = await client.uploadFile(filePath /*, uploader */);
    console.log("File Upload Successful!");
    console.log("IPFS Hash:", result.response.Hash);
    console.log("File Name:", result.response.Name);
    console.log("File Size:", result.response.Size);
    console.log("Transaction Receipt:", result.transactionReceipt);
  } catch (error) {
    console.error("File upload failed:", error);
  }
}

async function uploadMyDirectory() {
  try {
    const dirPath = path.resolve(__dirname, "path/to/your/directory"); // Use absolute path
    // Optionally specify an uploader address (must be a valid address string)
    // const uploader = "0xYourUploaderAddress";
    const result = await client.uploadDir(dirPath /*, uploader */);
    console.log("Directory Upload Successful!");
    // The last item in the response array is the base directory info
    const baseDirInfo = result.response.at(-1);
    if (baseDirInfo) {
      console.log("Base Directory IPFS Hash:", baseDirInfo.Hash);
      console.log("Base Directory Name:", baseDirInfo.Name);
      console.log("Base Directory Size:", baseDirInfo.Size);
    }
    console.log("Transaction Receipt:", result.transactionReceipt);
    // You can also inspect result.response for individual file details within the directory
    // console.log('All uploaded items:', result.response);
  } catch (error) {
    console.error("Directory upload failed:", error);
  }
}

uploadMyFile();
uploadMyDirectory();

API

WebhashClient

The main class for interacting with the WebHash network.

constructor(privateKey: string)

Creates a new WebhashClient instance.

• privateKey: string - Your wallet's private key (prefixed with 0x or not). This is used for signing uploads and registering content on chain.

async uploadFile(filePath: string, uploader?: string)

Uploads a single file to WebHash and registers it on-chain.

• filePath: string - The absolute path to the file you want to upload.
• uploader: string (optional) - The address of the uploader. If not provided, the client's wallet address is used.
• Returns: Promise<{ response: UploadResponse, transactionReceipt: TransactionReceipt }>
  • response: An object containing the Hash (CID), Name, and Size of the uploaded file.
  • transactionReceipt: The receipt from the blockchain transaction that registered the content.
• Throws: InvalidInput if the path is not a file or the uploader address is invalid. Forbidden if the signature is invalid. UploadFailed for other upload errors.

async uploadDir(dirPath: string, uploader?: string)

Uploads a directory and all its contents recursively to WebHash and registers the base directory on-chain.

• dirPath: string - The absolute path to the directory you want to upload.
• uploader: string (optional) - The address of the uploader. If not provided, the client's wallet address is used.
• Returns: Promise<{ response: UploadResponse[], transactionReceipt: TransactionReceipt }>
  • response: An array of UploadResponse objects. Each object represents an item (file or subdirectory) within the uploaded directory. The last element in the array corresponds to the base directory itself.
  • transactionReceipt: The receipt from the blockchain transaction that registered the base directory's content.
• Throws: InvalidInput if the path is not a directory, the directory is empty, or the uploader address is invalid. Forbidden if the signature is invalid. UploadFailed for other upload errors.

Types

UploadResponse

interface UploadResponse {
  Hash: string; // The IPFS hash (CID) of the uploaded content.
  Name: string; // The name of the uploaded file or directory.
  Size: string; // The size of the uploaded content in bytes (as a string).
}

TransactionReceipt

This is the standard transaction receipt object provided by viem.