Novisurf Storage SDK

Official JavaScript/TypeScript SDK for Novisurf Storage - Multi-node object storage with firewall analytics and quota management.

Features

• Multi-Node Object Storage (ONPREM/NF)
• ️ Firewall Analytics & Security
• 📊 Quota Tracking & Monitoring
• 🔑 API Key Management
• 🎯 TypeScript Support
• �️ File Preview Support
• 🌐 Public/Private Bucket Management

Installation

Install directly from GitHub:

npm install github:yourusername/dreambase-sdk
# or
yarn add github:yourusername/dreambase-sdk
# or
pnpm add github:yourusername/dreambase-sdk

Quick Start

import { Dreambase } from '@dreambase/sdk';

// Initialize with API Key + Secret Key (recommended for server-side)
const storage = new Dreambase({
  endpoint: process.env.DREAM_ENDPOINT, // e.g., 'https://api.novisurf.top'
  apiKey: process.env.DREAMBASE_API_KEY, // Access key from /getkey
  secretKey: process.env.DREAMBASE_SECRET_KEY, // Secret key from /getkey (required for write operations)
});

// Or initialize with JWT (for user-authenticated requests)
const storage = new Dreambase({
  endpoint: process.env.DREAM_ENDPOINT,
  jwt: userJwtToken,
});

The secretKey is required for all write operations (upload, delete, bucket creation). Read operations only require the apiKey.

Multi-Node Storage Support

Novisurf Storage supports multi-node infrastructure with automatic protocol detection:

• ONPREM: On-premise storage nodes (HTTP/HTTPS)
• NF: Cloudflare R2 compatible storage

The SDK automatically handles protocol types and provides seamless access to your storage buckets across different infrastructure. All public files are accessible via storage.novisurf.top.

// Get storage key with protocol information
const storageKey = await storage.getStorageKey('myproject');
console.log(storageKey.protocolType); // 'ONPREM' or 'NF'
console.log(storageKey.endpoint); // Storage endpoint URL
console.log(storageKey.domain); // 'storage.novisurf.top'

// Upload a file (works with any protocol type)
const fileContent = Buffer.from('Hello World').toString('base64');
await storage.uploadObject('myproject', 'hello.txt', fileContent, 'text/plain');

// List all objects
const { objects } = await storage.listStorageObjects('myproject');

// Access public files via storage.novisurf.top
// https://storage.novisurf.top/{bucket}/{filename}

Dashboard Features

The Novisurf Storage dashboard provides a comprehensive interface for managing your storage:

Project Overview

• Real-time storage quota monitoring (used/total)
• Read and write operation tracking
• Firewall analytics (requests denied, challenges issued)
• Quick actions for file management
• SDK integration guides
• Onboarding flow for new projects

Storage Browser

• File listing with metadata (name, size, type, created date)
• File preview modal for images, videos, and PDFs
• Direct file actions (copy URL, open in new tab, delete)
• Upload files with drag-and-drop support
• Public/private bucket management
• All public files accessible via storage.novisurf.top

Firewall Analytics

• Real-time request monitoring
• Denied requests tracking
• Challenge issuance statistics
• Security event logging

Project Settings

• API key management
• Storage configuration
• Quota limits and usage

Firewall Analytics

Track security events and firewall activity for your storage buckets:

// Firewall analytics are automatically loaded in the dashboard
// Access via the API endpoint:
// GET /waf/{bucket}/analytics

// Returns:
{
  denied: 42,      // Number of denied requests
  challenged: 15   // Number of challenges issued
}

The dashboard displays firewall metrics in real-time cards:

• Requests Denied (red card)
• Challenges Issued (amber card)

File Preview

The storage browser includes built-in file preview capabilities:

• Images: Full preview with proper sizing
• Videos: Video player with controls
• PDFs: Embedded iframe viewer
• Other files: Download or open in new tab

Preview counts as a read operation but provides instant file access without leaving the dashboard.

Usage Examples

Storage Operations

// Provision a storage bucket
const { ok, bucket, accessKey } = await storage.provisionStorageBucket('myproject');

// Get storage key with protocol information
const storageKey = await storage.getStorageKey('myproject');
console.log('Protocol:', storageKey.protocolType); // 'ONPREM' or 'NF'
console.log('Endpoint:', storageKey.endpoint);
console.log('Public Domain:', storageKey.domain); // 'storage.novisurf.top'
console.log('Is Public:', storageKey.public);

// Upload a file
const fileContent = Buffer.from('Hello World').toString('base64');
await storage.uploadObject('myproject', 'hello.txt', fileContent, 'text/plain');

// List all objects
const { bucket, objects, count } = await storage.listStorageObjects('myproject');
objects.forEach(obj => {
  console.log(obj.key, obj.size, obj.lastModified);
  // Public URL: https://storage.novisurf.top/{bucket}/{obj.key}
});

// Delete an object
await storage.deleteObject('myproject', 'hello.txt');

// Set bucket to public
await storage.setStorageBucketPublic('myproject', true);

// Get storage statistics
const stats = await storage.getStorageStats('myproject');
console.log('Total Files:', stats.totalFiles);
console.log('Total Bytes:', stats.totalBytes);

// Get a public file
const file = await storage.getPublicFile('myproject', 'file-id');

Error Handling

import { Dreambase, DreambaseError } from '@dreambase/sdk';

try {
  await storage.uploadObject('myproject', 'file.txt', content, 'text/plain');
} catch (error) {
  if (error instanceof DreambaseError) {
    console.error('Error:', error.message);
    console.error('Status:', error.statusCode);
    console.error('Details:', error.details);
  }
}

Environment Variables

Set your Novisurf endpoint and credentials in your environment:

DREAM_ENDPOINT=https://api.novisurf.top
DREAMBASE_API_KEY=your_access_key_here
DREAMBASE_SECRET_KEY=your_secret_key_here

Get your apiKey and secretKey by calling the /getkey endpoint with your Appwrite JWT token. Store both securely and never commit them to version control.

TypeScript Support

The SDK is written in TypeScript and includes full type definitions:

import { Dreambase, StorageStats } from '@dreambase/sdk';

const storage = new Dreambase({ 
  endpoint: process.env.DREAM_ENDPOINT!, 
  apiKey: 'key' 
});

// All responses are fully typed
const stats: StorageStats = await storage.getStorageStats('myproject');
const storageKey = await storage.getStorageKey('myproject');
console.log(storageKey.domain); // 'storage.novisurf.top'

API Reference

Constructor

• new Dreambase(config: DreambaseConfig)

Storage Methods

• getStorageKey(dbName?: string) - Get storage credentials and configuration (includes protocolType, endpoint, domain: 'storage.novisurf.top')
• provisionStorageBucket(dbName?: string) - Provision a new storage bucket
• setStorageBucketPublic(dbName: string | undefined, makePublic: boolean) - Set bucket public/private
• listStorageObjects(dbName?: string) - List all objects in bucket
• uploadObject(dbName: string | undefined, key: string, contentBase64: string, contentType?: string) - Upload a file
• deleteObject(dbName: string | undefined, key: string) - Delete a file
• getStorageStats(dbName?: string) - Get storage statistics (computed from object list)
• getPublicFile(dbName: string, fileId: string) - Get a public file

Utility Methods

• setEndpoint(endpoint: string) - Update API endpoint
• setApiKey(apiKey: string, secretKey?: string) - Update API key and optionally secret key
• setJwt(jwt: string) - Update JWT token

Rate Limits

• Write operations: 20 requests per minute
• Read operations: 50 requests per minute

Quotas (Free Tier)

• Storage: 1GB total storage per user
• Read Operations: Tracked per month for quota monitoring
• Write Operations: Tracked per month for quota monitoring
• Public Access: All public files served via storage.novisurf.top

Enhanced Quota Tracking

The SDK provides detailed quota information:

const quota = await storage.getQuota('myproject');

// Storage quota
console.log('Storage Used:', quota.storage?.used);
console.log('Storage Limit:', quota.storage?.limit);

// Operations tracking
console.log('Read Operations:', quota.operations?.reads);
console.log('Write Operations:', quota.operations?.writes);

The dashboard displays quota information in real-time cards:

• Storage Used (with progress bar)
• Read Operations (monthly count)
• Write Operations (monthly count)

Security Best Practices

1. API Keys: Store API keys in environment variables, never commit to version control
2. JWT Tokens: Use short-lived JWTs for client-side authentication
3. Bucket Privacy: Keep buckets private unless public access is required
4. Firewall Rules: Monitor firewall analytics for suspicious activity
5. Rate Limiting: Respect rate limits to avoid service disruption
6. Public URLs: All public files are accessible via storage.novisurf.top/{bucket}/{filename}

Troubleshooting

Storage Key Not Found

If you get a "Storage key not found" error, provision a bucket first:

await storage.provisionStorageBucket('myproject');

Protocol Type Issues

The SDK automatically handles different protocol types (ONPREM/NF). If you encounter issues:

• Check the protocolType field in storage key response
• Verify endpoint URL is accessible
• Ensure domain is properly configured (should be storage.novisurf.top)

Firewall Analytics Not Loading

Firewall analytics require:

• Valid storage bucket
• Firewall rules configured
• Proper authentication (API key or JWT)

File Preview Not Working

File preview requires:

• Public bucket or proper authentication
• Supported file type (images, videos, PDFs)
• Valid file URL with correct domain (storage.novisurf.top)

Rate Limiting

If you hit rate limits:

• Wait for the cooldown period (typically 60 seconds)
• Implement exponential backoff in your application
• Consider caching frequently accessed data

Public File Access

All public files are accessible via:

https://storage.novisurf.top/{bucket}/{filename}

Ensure your bucket is set to public if you want files to be accessible without authentication.

License

MIT

Support

For issues and questions:

• Visit: https://novisurf.top/support
• Email: [email protected]
• Documentation: https://docs.novisurf.top

Public Storage Domain

All public files are served via: storage.novisurf.top