@mifistix-cloud/storage

File Storage SDK for Mifistix Cloud - Upload, download, and manage files.

License

This module is licensed for internal use within Mifistix only. See LICENSE for details.

Installation

npm install @mifistix-cloud/storage

Quick Start

const { initializeApp } = require('@mifistix-cloud/app');
const { getStorage, storageReference, uploadBytes, getDownloadURL, deleteObject } = require('@mifistix-cloud/storage');

// Initialize app
const app = initializeApp({
  apiKey: 'your-api-key',
  projectId: 'your-project-id',
  storageBucket: 'your-project.mifistix.storage'
});

// Get storage instance
const storage = getStorage(app);

// Create reference
const fileRef = storageReference(storage, 'images/photo.jpg');

// Upload file
const result = await uploadBytes(fileRef, fileData, {
  contentType: 'image/jpeg',
  customMetadata: 'photo'
});

// Get download URL
const url = await getDownloadURL(fileRef);
console.log('Download URL:', url);

// Delete file
await deleteObject(fileRef);

API Reference

getStorage(app)

Get storage instance.

Parameters:

• app (Object, required): Initialized app instance

Returns: Storage service instance

storageReference(storage, filePath)

Create a reference to a file.

Parameters:

• storage (Object): Storage instance
• filePath (string, required): File path (validated for path traversal)

Returns: Storage reference with fullPath, name, bucket

Example:

const fileRef = storageReference(storage, 'images/photo.jpg');
console.log(fileRef.fullPath); // 'images/photo.jpg'
console.log(fileRef.name);     // 'photo.jpg'

uploadBytes(ref, data, metadata?)

Upload file to storage.

Parameters:

• ref (Object): Storage reference
• data (any, required): File data (string, Buffer, Blob)
• metadata (Object, optional): File metadata

Returns: Promise with object containing ref, metadata, name, url

Example:

const result = await uploadBytes(fileRef, fileData, {
  contentType: 'image/jpeg',
  title: 'My Photo'
});
console.log('File URL:', result.url);

getDownloadURL(ref)

Get public download URL for a file.

Parameters:

• ref (Object): Storage reference

Returns: Promise - Download URL

Example:

const url = await getDownloadURL(fileRef);

deleteObject(ref)

Delete a file from storage.

Parameters:

• ref (Object): Storage reference

Returns: Promise

Example:

await deleteObject(fileRef);

Security Features

• Path Traversal Protection: Validates file paths to prevent ../ attacks
• Data Validation: Validates required parameters
• Project Isolation: Uses project ID in all requests
• Error Handling: Throws appropriate error types

File Metadata

When uploading, you can include metadata:

await uploadBytes(fileRef, data, {
  contentType: 'image/jpeg',
  title: 'My Photo',
  category: 'images',
  customField: 'value'
});

Download URLs

Files are accessible via public URLs:

https://api-cloud.s-mifistix.pp.ua/api/storage/public/{projectId}/{filename}

Architecture

storage/
├── src/
│   ├── core/
│   │   └── StorageClient.js     # Main storage client
│   ├── services/
│   │   └── StorageService.js    # File operations
│   ├── utils/
│   │   └── helpers.js          # Helper functions
│   ├── types/
│   │   └── index.js            # Type definitions
│   └── config/
│       └── constants.js        # Configuration constants
└── index.js

License

MIT