NullDrop SDK

Official TypeScript/JavaScript SDK for NullDrop file sharing service

Features

• API v2 by default - Latest performance optimizations
• Privacy Controls - Public/private file uploads
• Bulk Operations - Upload and delete multiple files efficiently
• Backward Compatible - Full support for v1 API
• Universal - Works in browsers and Node.js
• TypeScript - Full type safety and IntelliSense
• Error Handling - Comprehensive error types and validation
• Performance - Built-in retry logic and request monitoring
• Developer Friendly - Fluent API with smart defaults

Installation

npm install @nulldrop/sdk

Quick Start

Basic Usage (v2 API)

import { NullDropClient } from '@nulldrop/sdk';

// Initialize client (v2 by default)
const client = new NullDropClient({
  apiKey: 'your-api-key'  // or set NULLDROP_API_KEY env var
});

// Upload a file with privacy control (v2 feature)
const result = await client.upload(file, { isPublic: false });
console.log(`Uploaded: ${result.filename} (Private: ${!result.isFilePublic()})`);

// Bulk upload multiple files (v2 feature)
const files = [file1, file2, file3];
const bulkResult = await client.uploadBulk(files, { 
  isPublic: true,
  maxConcurrent: 3 
});
console.log(`Uploaded ${bulkResult.totalUploaded} files successfully`);

v1 API Compatibility

// Explicitly use v1 API if needed
const clientV1 = new NullDropClient({
  apiKey: 'your-api-key',
  apiVersion: 'v1'
});

const result = await clientV1.upload(file);  // v1 behavior

What's New in v2

Enhanced Upload Response

const result = await client.upload(file, { isPublic: false });

// New v2 properties
console.log('Privacy:', result.isFilePublic());           // boolean
console.log('Performance:', result.getPerformanceMs());   // number (ms)
console.log('Formatted:', result.getFormattedPerformance()); // "45ms"

Bulk Operations

// Bulk Upload
const uploadResult = await client.uploadBulk(files, {
  isPublic: false,
  maxConcurrent: 3
});

// Bulk Delete  
const deleteResult = await client.deleteBulk(fileIds, {
  maxConcurrent: 5
});

console.log(`Success: ${uploadResult.totalUploaded}, Failed: ${uploadResult.totalFailed}`);

Performance & Privacy

• isPublic parameter: Control file visibility
• _perf field: Request duration in milliseconds
• Bulk operations: Parallel processing for better performance
• Backward compatible: All v1 code continues to work

Configuration

const client = new NullDropClient({
  apiKey: 'your-api-key',           // Required (or NULLDROP_API_KEY env var)
  apiVersion: 'v2',                 // 'v1' or 'v2' (default: v2)
  baseUrl: 'https://nulldrop.xyz/api', // API base URL
  timeout: 30000,                   // Request timeout (ms)
  retryAttempts: 3,                 // Retry failed requests
  debug: false                      // Enable debug logging
});

API Methods

Upload Operations

• upload(file, options?) - Upload single file with v2 options
• uploadBulk(files, options?) - Upload multiple files (v2 only)

File Management

• listFiles(options?) - List uploaded files with pagination
• getFile(fileId) - Get file details
• deleteFile(fileId) - Delete single file
• deleteBulk(fileIds, options?) - Delete multiple files (v2 only)

Utility Methods

• getDownloadUrl(fileId) - Get direct download URL
• getShareUrl(fileId) - Get shareable URL
• fileExists(fileId) - Check if file exists
• getFileCount() - Get total file count
• getApiVersion() - Get current API version
• isV2Api() - Check if using v2 API

Error Handling

import { ValidationError, AuthenticationError, RateLimitError } from '@nulldrop/sdk';

try {
  const result = await client.upload(file);
} catch (error) {
  if (error instanceof ValidationError) {
    console.error('Validation failed:', error.message);
  } else if (error instanceof AuthenticationError) {
    console.error('Auth failed:', error.message);
  } else if (error instanceof RateLimitError) {
    console.error('Rate limited:', error.retryAfter);
  }
}

Environment Support

• √ Node.js 16+
• √ Modern browsers (Chrome, Firefox, Safari, Edge)
• √ Web Workers
• √ TypeScript 4.0+
• √ ESM & CommonJS

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the GPL License - see the LICENSE file for details.

---

Made with ❤️ by Null Tools