npm package: @super-protocol/sp-files-addon
Description: SP-Files-Addon is a Node.js addon that provides functionality for uploading, downloading, and managing encrypted files and directories. It supports various storage types such as filesystem (FS), S3, and Storj.
Latest version: 0.13.2

# SP-Files-Addon

SP-Files-Addon is a Node.js addon that provides functionality for uploading, downloading, and managing encrypted files and directories. It supports various storage types such as filesystem (FS), S3, and Storj.

## Installation

```sh
npm install @super-protocol/sp-files-addon
```

## Usage

Here's a basic example of how to use the SP-Files-Addon:

```typescript
import { upload, download, calculateResourceHash, deleteResource, StorageConfig } from '@super-protocol/sp-files-addon';

// Example S3 storage configuration
const s3Storage: StorageConfig = {
  storageType: 'S3',
  endpoint: 'your-s3-endpoint',
  region: 'your-s3-region',
  bucket: 'your-s3-bucket',
  accessKeyId: 'your-access-key', // optional
  secretKey: 'your-secret-key'    // optional
};

// Example resource definition
const resource = {
  storage: s3Storage,
  prefix: 'resource/prefix'
};

// Upload example
const uploadOptions = {
  encryption: true, // or provide EncryptionWithIV object, or false to disable
  hashAlgorithm: 'sha256', // optional
  sourcePath: 'subfolder', // optional
  targetPath: 'destination', // optional
  progressCallback: (args) => {
    console.log(`Processing ${args.key}: ${args.current}/${args.total}`);
  }
};

upload('path/to/source', resource, uploadOptions)
  .then(result => {
    console.log('Upload result:', {
      hash: result.hash,
      encryption: result.encryption, // if encryption was enabled
      resource: result.resource
    });
  })
  .catch(err => console.error('Upload error:', err));

// Download example
const downloadOptions = {
  encryption: {
    key: 'hex-encoded-key',
    iv: 'hex-encoded-iv'
  },
  hashAlgorithm: 'sha256',
  sourcePath: 'source-prefix', // optional
  targetPath: 'target-prefix', // optional
  progressCallback: (args) => {
    console.log(`Downloading ${args.key}: ${args.current}/${args.total}`);
  }
};

download(resource, 'local/path', downloadOptions)
  .then(result => {
    console.log('Download result:', {
      hash: result.hash,
      size: result.size
    });
  })
  .catch(err => console.error('Download error:', err));

// Calculate resource hash
const hashOptions = {
  encryption: {
    key: 'hex-encoded-key',
    iv: 'hex-encoded-iv'
  },
  hashAlgorithm: 'sha256',
  path: 'subfolder', // optional
  progressCallback: (args) => {
    console.log(`Hashing ${args.key}: ${args.current}/${args.total}`);
  }
};

calculateResourceHash(resource, hashOptions)
  .then(hash => console.log('Resource hash:', hash))
  .catch(err => console.error('Hash calculation error:', err));

// Delete resource
deleteResource(resource)
  .then(() => console.log('Resource deleted'))
  .catch(err => console.error('Delete resource error:', err));
```

## API

### Storage Configuration

The addon supports three types of storage:

```typescript
type StorageConfig =
  | { storageType: 'FS', bucket: string }
  | { storageType: 'S3', endpoint: string, accessKeyId?: string, secretKey?: string, region?: string, bucket: string }
  | { storageType: 'STORJ', token: string, bucket: string }
```

### Main Functions

#### `upload(source: ResourceOrPath, target: ResourceOrPath, options?: UploadOptions): Promise<UploadResult>`

Clones the contents of a resource to another, encrypting the contents, calculating hash and syncing dirhashes if needed.

#### `download(source: ResourceOrPath, target: ResourceOrPath, options: DownloadOptions): Promise<DownloadResult>`

Clones the contents of a resource to another, decrypting the contents, calculating hash and comparing with original resource hash.

#### `calculateResourceHash(resource: ResourceOrPath, options?: HashOptions): Promise<Hash>`

Calculates resource hash of a directory or file.

#### `deleteResource(resource: ResourceOrPath): Promise<void>`

Deletes a resource and all its contents.

#### `smartServerCopy(source: ResourceOrPath, target: ResourceOrPath): Promise<ServerCopyResult>`

Performs an optimized server-side copy when possible.

### Constants

- `DIRHASH_FILE`: Constant defining the dirhash file name

For detailed type definitions and interfaces, please refer to the [TypeScript definitions](./index.d.ts).

## Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

Please make sure to update tests as appropriate.

## Benchmarks

The project includes benchmarks to measure the performance of various operations. To run the benchmarks:

```sh
yarn benchmark
```

For more information about the benchmarks, see the [benchmarks README](./benchmarks/README.md).

## License

[MIT](https://choosealicense.com/licenses/mit/)

## Acknowledgements

- [NAPI-RS](https://github.com/napi-rs) for providing the N-API bindings generator
- [Super Protocol](https://superprotocol.com/)