Wasabi SDK

A modern, developer-friendly SDK for Wasabi cloud storage with S3 compatibility. This SDK provides a simple and intuitive interface for interacting with Wasabi's cloud storage service.

Features

• 🚀 Modern Multi-Language SDKs with full type safety
• 🔧 S3 Compatible - Works seamlessly with Wasabi's S3-compatible API
• 📦 Easy to Use - Simple, intuitive API design
• 🛠️ CLI Tools - Command-line interfaces for quick operations
• 🔄 Async/Await Support - Modern JavaScript patterns
• 📊 Progress Tracking - Built-in progress callbacks for uploads/downloads
• 🔐 Security - Support for presigned URLs and encryption
• 🎯 Error Handling - Comprehensive error handling and retry logic
• 🌍 Multi-Language - Support for Node.js, PHP, and Python

Supported Languages

Node.js/TypeScript

npm install @nurudinso/wasabi-s3-sdk

PHP

composer require nurudinso/wasabi-s3-sdk

Python

pip install wasabi-s3-sdk

Quick Start

Node.js/TypeScript

import { WasabiClient } from '@nurudinso/wasabi-s3-sdk';

// Initialize the client
const client = new WasabiClient({
  accessKeyId: 'your-access-key',
  secretAccessKey: 'your-secret-key',
  region: 'us-east-1'
});

// List all buckets
const buckets = await client.listBuckets();
console.log('Buckets:', buckets);

// Create a new bucket
await client.createBucket('my-new-bucket');

// Get a bucket instance
const bucket = client.bucket('my-bucket');

// Upload a file
await bucket.uploadFile('./local-file.txt', 'remote-file.txt');

// Download a file
await bucket.downloadFile('remote-file.txt', './downloaded-file.txt');

PHP

<?php
require_once 'vendor/autoload.php';

use Nurudinso\WasabiS3Sdk\WasabiClient;

// Initialize the client
$client = new WasabiClient([
    'access_key_id' => 'your-access-key',
    'secret_access_key' => 'your-secret-key',
    'region' => 'us-east-1'
]);

// List all buckets
$buckets = $client->listBuckets();
echo "Buckets: " . implode(', ', $buckets) . "\n";

// Create a new bucket
$client->createBucket('my-new-bucket');

// Get a bucket instance
$bucket = $client->bucket('my-bucket');

// Upload a file
$bucket->uploadFile('./local-file.txt', 'remote-file.txt');

// Download a file
$bucket->downloadFile('remote-file.txt', './downloaded-file.txt');

Python

from wasabi_s3_sdk import WasabiClient

# Initialize the client
client = WasabiClient({
    'access_key_id': 'your-access-key',
    'secret_access_key': 'your-secret-key',
    'region': 'us-east-1'
})

# List all buckets
buckets = client.list_buckets()
print(f"Buckets: {buckets}")

# Create a new bucket
client.create_bucket('my-new-bucket')

# Get a bucket instance
bucket = client.bucket('my-bucket')

# Upload a file
bucket.upload_file('./local-file.txt', 'remote-file.txt')

# Download a file
bucket.download_file('remote-file.txt', './downloaded-file.txt')

CLI Tools

Node.js CLI

# Install globally
npm install -g wasabi-sdk

# List all buckets
wasabi bucket list

# Upload a file
wasabi object upload my-bucket my-file.txt ./local-file.txt

# Download a file
wasabi object download my-bucket my-file.txt ./downloaded-file.txt

PHP CLI

# Install via Composer
composer global require wasabi/sdk

# List all buckets
wasabi bucket:list

# Upload a file
wasabi object:upload my-bucket my-file.txt ./local-file.txt

# Download a file
wasabi object:download my-bucket my-file.txt ./downloaded-file.txt

Python CLI

# Install via pip
pip install wasabi-sdk

# List all buckets
wasabi bucket list

# Upload a file
wasabi object upload my-bucket my-file.txt ./local-file.txt

# Download a file
wasabi object download my-bucket my-file.txt ./downloaded-file.txt

Migration from AWS S3

The SDK includes powerful migration utilities to help you move your data from AWS S3 to Wasabi:

Node.js Migration

import { S3ToWasabiMigrator } from 'wasabi-sdk';

const migrator = new S3ToWasabiMigrator(
  {
    accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
    region: 'us-east-1'
  },
  {
    accessKeyId: process.env.WASABI_ACCESS_KEY_ID!,
    secretAccessKey: process.env.WASABI_SECRET_ACCESS_KEY!,
    region: 'us-east-1'
  }
);

// Estimate migration
const estimate = await migrator.estimateMigration({
  sourceBucket: 'my-s3-bucket',
  destinationBucket: 'my-wasabi-bucket'
});

// Perform migration
const result = await migrator.migrate({
  sourceBucket: 'my-s3-bucket',
  destinationBucket: 'my-wasabi-bucket',
  preserveMetadata: true,
  continueOnError: true,
  onProgress: (progress) => {
    console.log(`Progress: ${progress.percentage}%`);
  }
});

PHP Migration

<?php
use Wasabi\SDK\Migration\S3ToWasabiMigrator;

$migrator = new S3ToWasabiMigrator(
    [
        'access_key_id' => $_ENV['AWS_ACCESS_KEY_ID'],
        'secret_access_key' => $_ENV['AWS_SECRET_ACCESS_KEY'],
        'region' => 'us-east-1'
    ],
    [
        'access_key_id' => $_ENV['WASABI_ACCESS_KEY_ID'],
        'secret_access_key' => $_ENV['WASABI_SECRET_ACCESS_KEY'],
        'region' => 'us-east-1'
    ]
);

// Estimate migration
$estimate = $migrator->estimateMigration([
    'source_bucket' => 'my-s3-bucket',
    'destination_bucket' => 'my-wasabi-bucket'
]);

// Perform migration
$result = $migrator->migrate([
    'source_bucket' => 'my-s3-bucket',
    'destination_bucket' => 'my-wasabi-bucket',
    'preserve_metadata' => true,
    'continue_on_error' => true,
    'on_progress' => function($progress) {
        echo "Progress: {$progress['percentage']}%\n";
    }
]);

Python Migration

from wasabi_sdk.migration import S3ToWasabiMigrator

migrator = S3ToWasabiMigrator(
    {
        'access_key_id': os.getenv('AWS_ACCESS_KEY_ID'),
        'secret_access_key': os.getenv('AWS_SECRET_ACCESS_KEY'),
        'region': 'us-east-1'
    },
    {
        'access_key_id': os.getenv('WASABI_ACCESS_KEY_ID'),
        'secret_access_key': os.getenv('WASABI_SECRET_ACCESS_KEY'),
        'region': 'us-east-1'
    }
)

# Estimate migration
estimate = migrator.estimate_migration({
    'source_bucket': 'my-s3-bucket',
    'destination_bucket': 'my-wasabi-bucket'
})

# Perform migration
result = migrator.migrate({
    'source_bucket': 'my-s3-bucket',
    'destination_bucket': 'my-wasabi-bucket',
    'preserve_metadata': True,
    'continue_on_error': True,
    'on_progress': lambda progress: print(f"Progress: {progress['percentage']}%")
})

Migration CLI Commands

# Node.js
wasabi migrate s3-to-wasabi --source-bucket my-s3-bucket --dest-bucket my-wasabi-bucket

# PHP
wasabi migration:s3-to-wasabi --source-bucket=my-s3-bucket --dest-bucket=my-wasabi-bucket

# Python
wasabi migration s3-to-wasabi --source-bucket my-s3-bucket --dest-bucket my-wasabi-bucket

Configuration

Environment Variables

You can set credentials using environment variables:

# Wasabi credentials
export WASABI_ACCESS_KEY_ID="your-access-key"
export WASABI_SECRET_ACCESS_KEY="your-secret-key"
export WASABI_REGION="us-east-1"

# AWS S3 credentials (for migration)
export AWS_ACCESS_KEY_ID="your-aws-access-key"
export AWS_SECRET_ACCESS_KEY="your-aws-secret-key"

Configuration Options

Node.js/TypeScript

interface WasabiConfig {
  accessKeyId: string;           // Required: Wasabi access key ID
  secretAccessKey: string;       // Required: Wasabi secret access key
  region: string;                // Required: Wasabi region
  endpoint?: string;             // Optional: Custom endpoint URL
  useSSL?: boolean;              // Optional: Use SSL (default: true)
  forcePathStyle?: boolean;      // Optional: Force path style (default: true)
  timeout?: number;              // Optional: Request timeout in ms (default: 30000)
  maxRetries?: number;           // Optional: Max retries (default: 3)
}

PHP

$config = [
    'access_key_id' => 'your-access-key',        // Required
    'secret_access_key' => 'your-secret-key',    // Required
    'region' => 'us-east-1',                     // Required
    'endpoint' => 's3.wasabisys.com',            // Optional
    'use_ssl' => true,                           // Optional (default: true)
    'force_path_style' => true,                  // Optional (default: true)
    'timeout' => 30,                             // Optional (default: 30)
    'max_retries' => 3,                          // Optional (default: 3)
];

Python

config = {
    'access_key_id': 'your-access-key',          # Required
    'secret_access_key': 'your-secret-key',      # Required
    'region': 'us-east-1',                       # Required
    'endpoint': 's3.wasabisys.com',              # Optional
    'use_ssl': True,                             # Optional (default: True)
    'force_path_style': True,                    # Optional (default: True)
    'timeout': 30,                               # Optional (default: 30)
    'max_retries': 3,                            # Optional (default: 3)
}

Supported Regions

• us-east-1 - US East (N. Virginia)
• us-west-1 - US West (N. California)
• eu-central-1 - Europe (Frankfurt)
• ap-northeast-1 - Asia Pacific (Tokyo)

Migration Features

• ✅ Batch Processing - Efficient concurrent migration
• ✅ Progress Tracking - Real-time progress updates
• ✅ Error Handling - Continue on errors or stop on first failure
• ✅ Metadata Preservation - Keep original object metadata
• ✅ Selective Migration - Filter by prefix or limit object count
• ✅ Move Operations - Delete source objects after successful migration
• ✅ Cost Estimation - Estimate migration time and costs
• ✅ Resume Support - Handle interruptions gracefully

Examples

File Upload with Progress

Node.js

import { WasabiClient } from '@nurudinso/wasabi-s3-sdk';

const client = new WasabiClient({
  accessKeyId: process.env.WASABI_ACCESS_KEY_ID!,
  secretAccessKey: process.env.WASABI_SECRET_ACCESS_KEY!,
  region: 'us-east-1'
});

const bucket = client.bucket('my-bucket');

// Upload with progress tracking
await bucket.uploadFile('./large-file.zip', 'backups/large-file.zip', {
  contentType: 'application/zip',
  metadata: {
    'uploaded-by': 'my-app',
    'version': '1.0.0'
  },
  onProgress: (progress) => {
    console.log(`Upload progress: ${progress.percentage}%`);
  }
});

PHP

<?php
$bucket = $client->bucket('my-bucket');

$bucket->uploadFile('./large-file.zip', 'backups/large-file.zip', [
    'content_type' => 'application/zip',
    'metadata' => [
        'uploaded-by' => 'my-app',
        'version' => '1.0.0'
    ]
]);

Python

bucket = client.bucket('my-bucket')

bucket.upload_file('./large-file.zip', 'backups/large-file.zip', {
    'content_type': 'application/zip',
    'metadata': {
        'uploaded-by': 'my-app',
        'version': '1.0.0'
    }
})

Batch Operations

Node.js

import { WasabiClient } from '@nurudinso/wasabi-s3-sdk';
import * as path from 'path';

const client = new WasabiClient({
  accessKeyId: process.env.WASABI_ACCESS_KEY_ID!,
  secretAccessKey: process.env.WASABI_SECRET_ACCESS_KEY!,
  region: 'us-east-1'
});

const bucket = client.bucket('my-bucket');

// Upload multiple files
const files = ['./file1.txt', './file2.txt', './file3.txt'];

for (const file of files) {
  const key = `uploads/${path.basename(file)}`;
  console.log(`Uploading ${file} to ${key}...`);
  
  await bucket.uploadFile(file, key, {
    metadata: {
      'batch-upload': 'true',
      'upload-date': new Date().toISOString()
    }
  });
}

PHP

<?php
$files = ['./file1.txt', './file2.txt', './file3.txt'];

foreach ($files as $file) {
    $key = 'uploads/' . basename($file);
    echo "Uploading {$file} to {$key}...\n";
    
    $bucket->uploadFile($file, $key, [
        'metadata' => [
            'batch-upload' => 'true',
            'upload-date' => date('c')
        ]
    ]);
}

Python

import os

files = ['./file1.txt', './file2.txt', './file3.txt']

for file in files:
    key = f"uploads/{os.path.basename(file)}"
    print(f"Uploading {file} to {key}...")
    
    bucket.upload_file(file, key, {
        'metadata': {
            'batch-upload': 'true',
            'upload-date': datetime.now().isoformat()
        }
    })

Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

Node.js

# Clone the repository
git clone https://github.com/nurudinso/wasabi-s3-sdk.git
cd wasabi-s3-sdk

# Install dependencies
npm install

# Build the project
npm run build

# Run tests
npm test

PHP

# Clone the repository
git clone https://github.com/nurudinso/wasabi-s3-sdk.git
cd wasabi-s3-sdk/php

# Install dependencies
composer install

# Run tests
composer test

Python

# Clone the repository
git clone https://github.com/nurudinso/wasabi-s3-sdk.git
cd wasabi-s3-sdk/python

# Install dependencies
pip install -e .

# Run tests
pytest

License

MIT License - see LICENSE file for details.

Security

• 🔒 Security Policy - How to report security vulnerabilities
• 🛡️ Security Guide - Comprehensive security documentation
• ✅ Security Checklist - Security audit checklist
• 🔍 Security Audit Guide - How to conduct security audits
• 📧 Vulnerability Reporting - Detailed vulnerability reporting process

Legal & Licensing

• 📄 License - MIT License
• 📋 Licensing Guide - Comprehensive licensing documentation
• 🔗 Third-Party Licenses - Dependencies and their licenses
• ✍️ Contributor License Agreement - License agreement for contributors
• ✅ License Compliance Guide - How to ensure license compliance

Support

• 📖 Documentation
• 🐛 Issue Tracker
• 💬 Discussions
• 🔒 Security Issues - Report security vulnerabilities

Changelog

See CHANGELOG.md for a list of changes and version history.