#Documentation

Welcome to the Walbucket SDK documentation. Get started with decentralized media storage on Sui blockchain.

#Quick Links

#Getting Started

• Installation - Install the SDK
• Quick Start - Get up and running in minutes
• Configuration - Configure the SDK

#API Reference

#Core Operations

• Upload - Upload files to storage
• Retrieve - Retrieve files from storage
• Delete - Delete files
• Get Asset - Get asset metadata
• List - List all assets

#File Operations

• Rename - Rename assets
• Copy - Duplicate assets

#Folder Management

• Create Folder - Create folders
• Delete Folder - Delete folders
• Move to Folder - Organize assets in folders

#Sharing & Permissions

#Access Grants (Private Sharing)

• Share Asset - Grant access to specific users
• Revoke Share - Revoke user access
• List Access Grants - View all access grants
• Get Access Grant - Get grant details

#Shareable Links (Public Sharing)

• Create Shareable Link - Create public share links
• Deactivate Shareable Link - Disable public links
• Track Link Access - Monitor link usage
• List Shareable Links - View all shareable links
• Get Shareable Link - Get link details

#Advanced Topics

• Gas Strategies - Choose who pays gas fees
• Encryption Policies - Secure your files
• Error Handling - Handle errors gracefully
• Wallet Integration - Integrate with wallets

#About Walbucket

Walbucket SDK provides a simple, developer-friendly interface for storing and managing media files on the Sui blockchain using Walrus decentralized storage. With built-in encryption support via Seal, automatic URL generation, and flexible gas payment strategies, it's designed to make decentralized storage as easy as using traditional cloud storage services.

#Features

• ✅ Standalone SDK - No backend dependency
• ✅ Direct Sui Integration - Uses Sui gRPC and JSON-RPC clients
• ✅ Walrus Storage - Direct blob storage integration
• ✅ Seal Encryption - Optional client-side encryption
• ✅ API Key Authentication - On-chain API key validation
• ✅ Gas Strategies - Developer-sponsored or user-pays
• ✅ Type-Safe - Full TypeScript support
• ✅ Cloudinary-like API - Familiar developer experience
• ✅ Automatic URL Generation - File URLs automatically generated and returned
• ✅ Network Auto-Detection - Package IDs automatically selected based on network
• ✅ Sharing & Permissions - Granular access control for assets
• ✅ Folder Organization - Organize assets in folders
• ✅ Public Links - Create shareable links with optional expiration

#Latest Updates (v0.5.5)

#Sharing Features

• Enhanced sharing with granular permissions (read, write, admin)
• Password-protected shares
• Time-based expiration for shares and links
• Access grant management
• Shareable link management with access tracking
• Deactivate shareable links
• List and query all shares and links

#Developer Features

• Project-based API key organization
• API key permission management
• Rate limiting support
• API key expiration
• Enhanced analytics and usage tracking

#NPM Package

📦 Package: @walbucket/sdk

Current Version: 0.5.5

#Quick Example

import { Walbucket } from '@walbucket/sdk';

// Initialize
const walbucket = new Walbucket({
  apiKey: 'your-api-key',
  network: 'testnet',
  sponsorPrivateKey: 'your-private-key',
});

// Upload a file
const { assetId, url } = await walbucket.upload(file, {
  name: 'photo.jpg',
  folder: 'gallery'
});

// Share with specific user
await walbucket.shareAsset(assetId, recipientAddress, {
  canRead: true,
  expiresAt: Date.now() + (7 * 24 * 60 * 60 * 1000) // 7 days
});

// Create public link
const shareToken = crypto.randomUUID();
await walbucket.createShareableLink(assetId, {
  shareToken,
  canRead: true,
  expiresAt: Date.now() + (24 * 60 * 60 * 1000) // 24 hours
});
const shareUrl = `https://yourapp.com/share/${shareToken}`;

// Retrieve file
const { data, metadata } = await walbucket.retrieve(assetId);

#Sharing Workflows

#Private Sharing (Access Grants)

For sharing with specific wallet addresses:

1. Create grant with shareAsset()
2. Set permissions (read/write/admin)
3. Optional: Set expiration and password
4. Monitor with listAccessGrants()
5. Revoke with revokeShare() when needed

#Public Sharing (Shareable Links)

For creating public share links:

1. Generate unique token with crypto.randomUUID()
2. Create link with createShareableLink()
3. Share the URL containing the token
4. Track access with trackLinkAccess()
5. Monitor with listShareableLinks()
6. Deactivate with deactivateShareableLink() when needed

#Common Patterns

#Full Access Management

// 1. Upload file
const { assetId } = await walbucket.upload(file);

// 2. Share with team member
await walbucket.shareAsset(assetId, teamMemberAddress, {
  canRead: true,
  canWrite: true
});

// 3. Create public link
const token = crypto.randomUUID();
await walbucket.createShareableLink(assetId, {
  shareToken: token,
  canRead: true,
  expiresAt: Date.now() + (7 * 24 * 60 * 60 * 1000)
});

// 4. Monitor all access
const grants = await walbucket.listAccessGrants();
const links = await walbucket.listShareableLinks();

console.log(`Shared with ${grants.length} users`);
console.log(`${links.length} public links created`);

#Support

For issues, questions, or contributions, visit the GitHub repository.