npm package: @galliun/walrus-sdk
Description: TypeScript SDK for Walrus API
Author: Your Name
Latest version: 1.0.0

# Walrus SDK Documentation

The Walrus SDK is a TypeScript library that provides an interface to interact with the Walrus storage system. It allows users to store and retrieve data using the Walrus Publisher and Aggregator.


## Installation

To install the Walrus SDK, use npm:

```bash
npm install @galliun/walrus-sdk
```

## Usage

First, import the WalrusSDK class:

```typescript
import WalrusSDK from 'walrus-sdk';
```

Then, create an instance of the SDK:

```typescript
const walrus = new WalrusSDK({
  aggregatorUrl: 'https://your-aggregator-url.com',
  publisherUrl: 'https://your-publisher-url.com'
});
```

If you don't provide URLs, the SDK will use default testnet URLs.

## API Reference

### Constructor

```typescript
constructor(config: WalrusConfig = {})
```

Creates a new instance of the WalrusSDK.

- `config`: An optional configuration object with the following properties:
  - `aggregatorUrl`: The URL of the Walrus aggregator (default: 'https://aggregator.walrus-testnet.walrus.space')
  - `publisherUrl`: The URL of the Walrus publisher (default: 'https://publisher.walrus-testnet.walrus.space')

### Methods

#### store

```typescript
async store(data: string | ArrayBuffer, options: StoreOptions = {}): Promise<StoreResponse>
```

Stores data in the Walrus network.

- `data`: The data to store (string or ArrayBuffer)
- `options`: An optional object with the following properties:
  - `epochs`: Number of epochs to store the data
  - `force`: Force storage even if the data already exists
  - `deletable`: Whether the data can be deleted

Returns a Promise that resolves to a `StoreResponse` object, which can be either a `NewlyCreatedResponse` or an `AlreadyCertifiedResponse`.

#### read

```typescript
async read(blobId: string): Promise<string>
```

Reads data from the Walrus network and returns it as a string.

- `blobId`: The ID of the blob to read

Returns a Promise that resolves to the data as a string.

#### readAsBuffer

```typescript
async readAsBuffer(blobId: string): Promise<ArrayBuffer>
```

Reads data from the Walrus network and returns it as an ArrayBuffer.

- `blobId`: The ID of the blob to read

Returns a Promise that resolves to the data as an ArrayBuffer.

#### readAsStream

```typescript
async readAsStream(blobId: string): Promise<ReadableStream>
```

Reads data from the Walrus network and returns it as a ReadableStream.

- `blobId`: The ID of the blob to read

Returns a Promise that resolves to a ReadableStream of the data.


## Error Handling

The SDK throws errors in the following cases:

1. If the Publisher URL is not set when calling `store`.
2. If the Aggregator URL is not set when calling `read`, `readAsBuffer`, or `readAsStream`.
3. If there's an HTTP error during any API call.
4. If the response body is null when calling `readAsStream`.

Make sure to wrap your SDK calls in try-catch blocks to handle these errors appropriately.

## Examples

Here's an example of how to use the Walrus SDK to store and retrieve data:

```typescript
import WalrusSDK from 'walrus-sdk';

const walrus = new WalrusSDK();

async function storeAndRetrieveData() {
  try {
    // Store data
    const storeResponse = await walrus.store('Hello, Walrus!', { epochs: 5 });
    
    if ('newlyCreated' in storeResponse) {
      const blobId = storeResponse.newlyCreated.blobObject.blobId;
      console.log(`Data stored with Blob ID: ${blobId}`);
      
      // Retrieve data
      const retrievedData = await walrus.read(blobId);
      console.log(`Retrieved data: ${retrievedData}`);
    } else {
      console.log('Data was already certified:', storeResponse.alreadyCertified);
    }
  } catch (error) {
    console.error('An error occurred:', error);
  }
}

storeAndRetrieveData();