npm package: @outpost67/sdk
Description: The official TypeScript SDK for Outpost67.
Author: Filebase
Latest version: 1.0.0


# @outpost67/sdk

The official TypeScript SDK for **Outpost 67**, a stablecoin prepayment storage network.  
Compatible with **Node.js** and **Browser** environments.

[![npm version](https://img.shields.io/npm/v/@outpost67/sdk.svg)](https://www.npmjs.com/package/@outpost67/sdk)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## Features

- **Decentralized Storage**: Upload files to the Outpost 67 network with various storage tiers.
- **Micro-Payments**: Built-in support for the x402 payment protocol using EVM (Ethereum compatible) and SVM (Solana) wallets.
- **Dual Support**: Works seamlessly in both Node.js (Buffers, Streams, Files) and Browser (File, Blob) environments.
- **Full Lifecycle Management**: Upload, retrieve, list, renew, and delete objects.

## Installation

```bash
npm install @outpost67/sdk
```

## Quick Start

### Initialize Client

You can initialize the client for either EVM or SVM networks.

**EVM (Ethereum, Polygon, Base, etc.)**

```typescript
import { Outpost67Client } from '@outpost67/sdk';

const privateKey = '0x...'; // Your EVM private key
const client = new Outpost67Client('evm', privateKey, {
    mode: 'live' // or 'test'
});
```

**SVM (Solana)**

```typescript
import { Outpost67Client } from '@outpost67/sdk';

const privateKey = '...'; // Your base58 API/Private key
const client = new Outpost67Client('svm', privateKey, {
    mode: 'live' // or 'test'
});
```

### Upload a File

**Node.js Example**

```typescript
import fs from 'fs';

// Upload a file stream
const stream = fs.createReadStream('./my-document.pdf');
const stats = fs.statSync('./my-document.pdf');

const upload = await client.upload('my-document.pdf', stream, {
    tier: 'standard',
    duration: 24, // hours
    explicitSize: stats.size // Required for streams
});

console.log('Upload successful:', upload.id);
```

**Browser Example**

```typescript
const fileInput = document.querySelector('input[type="file"]');
const file = fileInput.files[0];

const upload = await client.upload(file.name, file, {
    tier: 'standard',
    duration: 24
});

console.log('Upload successful:', upload.id);
```

### Retrieve a File

```typescript
// Returns a ReadableStream in Node.js or a Blob in the Browser
const result = await client.retrieve(upload.id);

// Node.js: Pipe to file
const dest = fs.createWriteStream('./downloaded.pdf');
result.pipe(dest);

// Browser: Create object URL
const url = URL.createObjectURL(result);
window.open(url);
```

## API Reference

### `constructor(network, privateKey, options)`

- **network**: `'evm' | 'svm'` - The blockchain network to use for payments.
- **privateKey**: `string` - The hex string (EVM) or base58 string (SVM) private key.
- **options**: `ClientOptions`
  - `mode`: `'live' | 'test'` (default: 'live')
  - `endpoint`: Custom API endpoint (optional)

### `upload(fileName, fileItem, params)`

Uploads a file to specific storage tier.

- **fileName**: `string` - The name of the file.
- **fileItem**: `File | Blob | Buffer | Readable | string` - The file content or path.
- **params**: `UploadParams`
  - `tier`: `'decentralized' | 'fast' | 'standard' | 'infrequent' | 'cold'`
  - `duration`: Storage duration in hours.
  - `explicitSize`: (Required for Streams) Size of the file in bytes.

### `list(filter?)`

List all objects in your storage.

- **filter**: `string` (optional) - Regex filter for the list.

### `retrieve(objectIdOrName, retrievalToken?)`

Download a file.

- **objectIdOrName**: `string` - The ID or name of the file.
- **retrievalToken**: `string` (optional) - Token for authorization if required.

### `renew(objectIdOrName, duration, renewalToken?)`

Extend the storage duration of a file.

- **duration**: `number` - Additional hours to store.

### `rotate(objectIdOrName, rotateToken?)`

Rotate access tokens for an object.

### `delete(objectIdOrName, deleteToken?)`

Delete a file from storage.

### `restore(objectIdOrName, newObjectName, duration, restoreToken?)`

Restore a file from `cold` storage.

- **newObjectName**: `string` - Name for the restored copy.
- **duration**: `number` - How long to keep the restored copy.

## Types

### StorageTier
`'decentralized' | 'fast' | 'standard' | 'infrequent' | 'cold'`

### UploadParams
```typescript
interface UploadParams {
    tier: StorageTier;
    duration: number; // hours
    explicitSize?: number; // bytes
}
```