@stoar/sdk/dist/s3/index.d.ts

JavaScript/TypeScript SDK for STOAR - Decentralized file storage on Arweave

import { S3CompatibleConfig, S3PutObjectParams, S3GetObjectParams, S3ListObjectsParams } from '../types';
import { StoarClient } from '../client';
import { LocalStorageManager, type LocalStorageConfig } from './local-storage';
/**
 * S3-compatible API layer for STOAR
 * Provides familiar S3-like methods for interacting with Arweave storage
 */
export declare class StoarS3Client {
    private stoarClient;
    private config;
    private localStorage;
    private manifestManager;
    private versionManager;
    private bucketRegistry;
    private costCalculator;
    constructor(stoarClient: StoarClient, config: S3CompatibleConfig, localStorageConfig?: LocalStorageConfig);
    /**
     * Put an object (equivalent to S3 putObject)
     * Now with version support
     */
    putObject(params: S3PutObjectParams): Promise<{
        ETag: string;
        Location: string;
        Bucket: string;
        Key: string;
        VersionId: string;
    }>;
    /**
     * Get an object (equivalent to S3 getObject)
     * Now supports version retrieval
     */
    getObject(params: S3GetObjectParams & {
        VersionId?: string;
    }): Promise<{
        Body: Uint8Array;
        ContentType?: string;
        ContentLength: number;
        ETag: string;
        LastModified: Date;
        VersionId: string;
        Metadata: Record<string, string>;
    }>;
    /**
     * List objects (equivalent to S3 listObjects)
     */
    listObjects(params?: S3ListObjectsParams): Promise<{
        IsTruncated: boolean;
        Contents: Array<{
            Key: string;
            LastModified: Date;
            ETag: string;
            Size: number;
            StorageClass: string;
        }>;
        Name: string;
        Prefix?: string;
        MaxKeys: number;
        Marker?: string;
    }>;
    /**
     * Delete an object (equivalent to S3 deleteObject)
     * Note: In Arweave, data is permanent and cannot be deleted
     */
    deleteObject(params: S3GetObjectParams): Promise<never>;
    /**
     * Check if an object exists (equivalent to S3 headObject)
     */
    headObject(params: S3GetObjectParams): Promise<{
        ContentType?: string;
        ContentLength: number;
        ETag: string;
        LastModified: Date;
        Metadata: Record<string, string>;
    }>;
    /**
     * Copy an object (equivalent to S3 copyObject)
     */
    copyObject(params: {
        CopySource: string;
        Key: string;
        Metadata?: Record<string, string>;
        MetadataDirective?: 'COPY' | 'REPLACE';
    }): Promise<{
        ETag: string;
        LastModified: Date;
    }>;
    /**
     * Helper method to get data size
     */
    private getDataSize;
    /**
     * Helper method to convert S3 metadata to Arweave tags
     */
    private convertMetadataToTags;
    /**
     * Helper method to extract S3 metadata from Arweave tags
     */
    private extractS3Metadata;
    /**
     * Create a new bucket with manifest support
     */
    createBucket(bucketName: string): Promise<{
        manifestId: string;
        bucketUrl: string;
    }>;
    /**
     * Update a bucket manifest with new files
     */
    updateBucketManifest(params: {
        bucketName: string;
        manifestId: string;
        updates: Array<{
            operation: 'add' | 'remove';
            key: string;
            txId?: string;
            size?: number;
        }>;
    }): Promise<{
        manifestId: string;
        bucketUrl: string;
        version: number;
    }>;
    /**
     * Get bucket info from local storage
     */
    getBucketInfo(bucketName: string): {
        state: ReturnType<LocalStorageManager['getBucketState']>;
        manifestHistory: ReturnType<LocalStorageManager['getManifestHistory']>;
    };
    /**
     * List all buckets from local storage
     */
    listLocalBuckets(): string[];
    /**
     * Export bucket as HTML
     */
    exportBucketHtml(bucketName: string): string;
    /**
     * List all versions of objects in a bucket
     */
    listObjectVersions(params: {
        Bucket: string;
        Prefix?: string;
        KeyMarker?: string;
        VersionIdMarker?: string;
        MaxKeys?: number;
    }): Promise<{
        IsTruncated: boolean;
        KeyMarker?: string;
        VersionIdMarker?: string;
        Versions: Array<{
            Key: string;
            VersionId: string;
            IsLatest: boolean;
            LastModified: Date;
            ETag: string;
            Size: number;
            Owner: string;
        }>;
    }>;
    /**
     * Get bucket history by traversing manifest chain
     */
    getBucketHistory(bucket: string, limit?: number): Promise<{
        History: Array<{
            ManifestId: string;
            ManifestVersion: number;
            Timestamp: Date;
            Operation: string;
            ChangedKey?: string;
            Actor: string;
            PreviousManifest?: string;
        }>;
    }>;
    /**
     * Estimate costs for operations
     */
    estimateCost(operations: Array<{
        type: 'putObject' | 'createBucket' | 'updateManifest';
        size?: number;
    }>): Promise<{
        breakdown: Array<{
            operation: string;
            costAR: string;
            costUSD: string;
        }>;
        totalAR: string;
        totalUSD: string;
        warning?: string;
    }>;
    /**
     * Format bytes to human readable format
     */
    private formatBytes;
    /**
     * List all buckets (S3-compatible)
     * Discovers buckets from the blockchain
     */
    listBuckets(): Promise<{
        Buckets: Array<{
            Name: string;
            CreationDate: Date;
        }>;
        Owner: {
            ID: string;
            DisplayName: string;
        };
    }>;
    /**
     * Remove an object from manifest (soft delete)
     * The file data still exists on Arweave but won't appear in bucket listings
     */
    removeFromManifest(bucket: string, key: string): Promise<{
        ManifestVersion: number;
        ManifestId: string;
        RemovedKey: string;
        Note: string;
    }>;
    /**
     * Get file icon based on extension/type
     */
    private getFileIcon;
    /**
     * Generate index.html for a bucket
     */
    private generateIndexHtml;
}
//# sourceMappingURL=index.d.ts.map