{"_id":"@clouduploader/clouduploader-js","_rev":"3-deef1202c23a97464dcae0a6a6d8fc3b","name":"@clouduploader/clouduploader-js","dist-tags":{"latest":"1.0.4"},"versions":{"1.0.2":{"name":"@clouduploader/clouduploader-js","version":"1.0.2","keywords":["cloud","uploader","upload","file","sdk"],"author":{"name":"CloudUploader"},"license":"MIT","_id":"@clouduploader/clouduploader-js@1.0.2","maintainers":[{"name":"clouduploader-js","email":"myb40971@gmail.com"}],"homepage":"https://github.com/CloudUploader/clouduploader-js#readme","bugs":{"url":"https://github.com/CloudUploader/clouduploader-js/issues"},"dist":{"shasum":"404ee0353f22b9ff172db9973d143b5a93a83ca8","tarball":"https://registry.npmjs.org/@clouduploader/clouduploader-js/-/clouduploader-js-1.0.2.tgz","fileCount":16,"integrity":"sha512-FDNsgLloLXfKVUHko1d6OFnxwubK7X/39YncS9zqqNXW+Oiq85J2dJ+qL5Ku03WMkhhWs/6Z5ZRv7YKcDqixhA==","signatures":[{"sig":"MEUCIQCue/dlLyjfsWm35XWoqufVUc1sMWCDlPJA7+kt1w0ujgIgLGMo7bW8mT8YC3lg4Dx008qZU2U2osNIMIKsFx2cn4Q=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":41499},"main":"dist/index.js","types":"dist/index.d.ts","gitHead":"4674941a9d393b0933cc6cee8f4684394f88d904","scripts":{"test":"echo \"Error: no test specified\" && exit 1"},"_npmUser":{"name":"clouduploader-js","email":"myb40971@gmail.com"},"repository":{"url":"git+https://github.com/CloudUploader/clouduploader-js.git","type":"git"},"_npmVersion":"10.8.2","description":"JavaScript SDK for CloudUploader - A comprehensive cloud file upload solution","directories":{},"_nodeVersion":"20.20.1","dependencies":{"glob":"^13.0.6","axios":"^1.15.0","p-map":"^4.0.0","mime-types":"^3.0.2","axios-retry":"^4.5.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"jest":"^30.3.0","nock":"^14.0.12","ts-jest":"^29.4.9","typescript":"^6.0.2","@types/glob":"^8.1.0","@types/jest":"^30.0.0","@types/node":"^25.6.0","@types/mime-types":"^3.0.1"},"_npmOperationalInternal":{"tmp":"tmp/clouduploader-js_1.0.2_1776334274364_0.4711227764611172","host":"s3://npm-registry-packages-npm-production"}},"1.0.3":{"name":"@clouduploader/clouduploader-js","version":"1.0.3","keywords":["cloud","uploader","upload","file","sdk"],"author":{"name":"CloudUploader"},"license":"MIT","_id":"@clouduploader/clouduploader-js@1.0.3","maintainers":[{"name":"clouduploader-js","email":"myb40971@gmail.com"}],"homepage":"https://github.com/CloudUploader/clouduploader-js#readme","bugs":{"url":"https://github.com/CloudUploader/clouduploader-js/issues"},"dist":{"shasum":"30c0eea6b1d4dc9784d10af2ebd84d7a430c6241","tarball":"https://registry.npmjs.org/@clouduploader/clouduploader-js/-/clouduploader-js-1.0.3.tgz","fileCount":21,"integrity":"sha512-3+Ezb+C8Ukf9guK/K1PD+90x862BGoQl15QXFRayWPAbXW0h8GxhqyufWy6mNujYPjD5NVKx3XIUpVHALeoS5g==","signatures":[{"sig":"MEUCIElYDKJ4kvUv+rLxg8PQI97bVlQbDQdoHS5rOAsfoYfSAiEA9rtEiQeRRVXvUML1qQ1NAoTBB4KMZV/EsvruuVaPOVw=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":51513},"main":"dist/index.js","types":"dist/index.d.ts","gitHead":"8485cd501fc1bd6a188968061da28495cf8ad0a1","scripts":{"dev":"npx tsc --watch","test":"jest","build":"npx tsc","prepublishOnly":"npm run build"},"_npmUser":{"name":"clouduploader-js","email":"myb40971@gmail.com"},"repository":{"url":"git+https://github.com/CloudUploader/clouduploader-js.git","type":"git"},"_npmVersion":"10.8.2","description":"JavaScript SDK for CloudUploader - A comprehensive cloud file upload solution","directories":{},"_nodeVersion":"20.20.1","dependencies":{"glob":"^13.0.6","axios":"^1.15.0","p-map":"^4.0.0","mime-types":"^3.0.2","axios-retry":"^4.5.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"jest":"^30.3.0","nock":"^14.0.12","ts-jest":"^29.4.9","typescript":"^6.0.2","@types/glob":"^8.1.0","@types/jest":"^30.0.0","@types/node":"^25.6.0","@types/mime-types":"^3.0.1"},"_npmOperationalInternal":{"tmp":"tmp/clouduploader-js_1.0.3_1776339124862_0.6175884178300419","host":"s3://npm-registry-packages-npm-production"}},"1.0.4":{"name":"@clouduploader/clouduploader-js","version":"1.0.4","main":"dist/index.js","types":"dist/index.d.ts","scripts":{"build":"npx tsc","dev":"npx tsc --watch","test":"jest","prepublishOnly":"npm run build"},"keywords":["cloud","uploader","upload","file","sdk"],"author":{"name":"CloudUploader"},"license":"MIT","description":"JavaScript SDK for CloudUploader - A comprehensive cloud file upload solution","publishConfig":{"access":"public"},"repository":{"type":"git","url":"git+https://github.com/CloudUploader/clouduploader-js.git"},"bugs":{"url":"https://github.com/CloudUploader/clouduploader-js/issues"},"homepage":"https://github.com/CloudUploader/clouduploader-js#readme","dependencies":{"@clouduploader/clouduploader-js":"^1.0.3","axios":"^1.15.0","axios-retry":"^4.5.0","glob":"^13.0.6","mime-types":"^3.0.2","p-map":"^4.0.0"},"devDependencies":{"@types/glob":"^8.1.0","@types/jest":"^30.0.0","@types/mime-types":"^3.0.1","@types/node":"^25.6.0","jest":"^30.3.0","nock":"^14.0.12","ts-jest":"^29.4.9","typescript":"^6.0.2"},"_id":"@clouduploader/clouduploader-js@1.0.4","gitHead":"f9878d6a163ab71430eeec2e967a22e661aa2315","_nodeVersion":"20.20.1","_npmVersion":"10.8.2","dist":{"integrity":"sha512-+K65jC0nlJ8eUmIbH8psAx7P1nBqWNpsGYj2ZiaN2/geXNuxeotHSHJJWTrTXFrr79n/I3VLh0ppQB4QvvpV2Q==","shasum":"f36f36ecd72c56215d42f42b43102b519110d64d","tarball":"https://registry.npmjs.org/@clouduploader/clouduploader-js/-/clouduploader-js-1.0.4.tgz","fileCount":21,"unpackedSize":54827,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCuQ7CJXPEyWFM/vdsxGKCFo79QZD0to5AOcUL486b0ugIhAL1HlzOuNIUfsa6AHiNDW479+6HZDmIG46/bfK0c0ljV"}]},"_npmUser":{"name":"clouduploader-js","email":"myb40971@gmail.com"},"directories":{},"maintainers":[{"name":"clouduploader-js","email":"myb40971@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/clouduploader-js_1.0.4_1776679400082_0.8592054072102158"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-16T10:11:14.212Z","modified":"2026-04-20T10:03:20.364Z","1.0.2":"2026-04-16T10:11:14.501Z","1.0.3":"2026-04-16T11:32:05.004Z","1.0.4":"2026-04-20T10:03:20.227Z"},"bugs":{"url":"https://github.com/CloudUploader/clouduploader-js/issues"},"author":{"name":"CloudUploader"},"license":"MIT","homepage":"https://github.com/CloudUploader/clouduploader-js#readme","keywords":["cloud","uploader","upload","file","sdk"],"repository":{"type":"git","url":"git+https://github.com/CloudUploader/clouduploader-js.git"},"description":"JavaScript SDK for CloudUploader - A comprehensive cloud file upload solution","maintainers":[{"name":"clouduploader-js","email":"myb40971@gmail.com"}],"readme":"# CloudUploader JavaScript SDK\n\n[![npm version](https://badge.fury.io/js/%40clouduploader%2Fclouduploader-js.svg)](https://www.npmjs.com/package/@clouduploader/clouduploader-js)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\nA highly-concurrent, low-latency JavaScript/TypeScript SDK for the **CloudUploader** platform. \n\nThis SDK natively interfaces with CloudUploader endpoints (`/api/upload/iaas/create`, `/complete`, etc.) to provide extreme performance for single files and massively parallel directory structures via chunked, multipart processing. Designed rigorously for Node.js, it bounds I/O aggressively without exhausting the V8 Garbage Collector or HTTP sockets.\n\n## Features\n\n| Feature | Details |\n|---|---|\n| **Simple API** | Upload any file or folder with one method call. |\n| **P-Map Concurrency** | Safely controls concurrent execution boundaries for folder uploads without exhausting the Node Event Loop (unlike naive `Promise.all`). |\n| **TCP Optimizations** | Pre-bundled with `http.Agent` pushing `{ maxSockets: 100, keepAlive: true }` to eliminate socket acquisition freezes on large batch transactions. |\n| **Multipart & Direct Routing** | Submits small files directly via PUT, whilst dynamically chunking large files across parallel streaming threads. |\n| **TypeScript Native** | Compile-time typings shipped right out of the box (`ES2022`). |\n| **Config-Driven** | Centralized configuration via `config.json` for easy management across environments. |\n| **Comprehensive Error Handling** | Precise error types for robust error handling in production. |\n| **Progress Tracking** | Real-time upload/download progress callbacks. |\n\n---\n\n## Installation\n\nInstall the package from npm:\n\n```bash\nnpm install @clouduploader/clouduploader-js\n```\n\nOr with yarn:\n\n```bash\nyarn add @clouduploader/clouduploader-js\n```\n\n---\n\n## Quick Start\n\nInitialize the `CloudUploader` client in your application:\n\n```typescript\nimport { CloudUploader } from '@clouduploader/clouduploader-js';\n\nconst uploader = new CloudUploader('ck_live_xxx', {\n    baseUrl: 'http://localhost:8080',   // Root backend (loaded from config.json by default)\n    maxParallelUploads: 5,              // Dynamic concurrency limit (default: 5)\n    storage: 'r2',                      // Cloud target (r2, s3, azure, minio, gcs)\n    maxRetries: 3,                      // Exponential backoff attempts\n    timeout: 30000                      // Request timeout in ms\n});\n```\n\n---\n\n## Configuration\n\n### Via Environment/Options\n\nThe SDK supports both configuration file and runtime options:\n\n```typescript\nimport { CloudUploader } from '@clouduploader/clouduploader-js';\n\nconst uploader = new CloudUploader('ck_live_xxx', {\n    baseUrl: 'https://api.clouduploader.com',  // Override config.json\n    maxParallelUploads: 10,\n    storage: 's3',\n    maxRetries: 5,\n    timeout: 45000,\n    chunkSizeOverride: 5242880 // 5MB chunks\n});\n```\n\n### Via config.json\n\nCreate a `config.json` in your project root:\n\n```json\n{\n  \"baseUrl\": \"http://localhost:8080\"\n}\n```\n\nThe SDK will automatically read this file when no `baseUrl` is provided in options.\n\n---\n\n## Usage Examples\n\n### 1. Single File Upload\n\n### 1. Single File Upload\n\nUpload a singular file seamlessly. The orchestrator will automatically negotiate direct routing vs parallel chunked sequences if the file is massive!\n\n```typescript\nasync function uploadMyVideo() {\n    try {\n        const result = await uploader.uploadFile('./assets/video.mp4');\n        console.log(`Success! File stored at: ${result.storage_path}`);\n        // -> \"r2://my-bucket/ab/cd/video.mp4\"\n    } catch (err) {\n        console.error(\"Upload failed\", err);\n    }\n}\n\nuploadMyVideo();\n```\n\n#### Progress Tracking\n\nMonitor upload progress in real-time:\n\n```typescript\nconst result = await uploader.uploadFile(\n    './assets/very_large_dataset.csv', \n    (uploadedBytes, totalBytes) => {\n        const pct = (uploadedBytes / totalBytes) * 100;\n        process.stdout.write(`\\rProgress: ${pct.toFixed(1)}%`);\n    }\n);\n```\n\n#### Storage Override\n\nPush a specific file to a different storage backend:\n\n```typescript\nconst result = await uploader.uploadFile(\n    './assets/backup.zip',\n    undefined,\n    's3'  // Override default storage for this upload\n);\n```\n\n---\n\n### 2. Mass Folder Upload (High Concurrency)\n\nRapidly sync an entire directory recursively to the backend. Files are mapped via internal concurrency throttling (`p-map`), ensuring low latency network scheduling.\n\n```typescript\nasync function backupAssets() {\n    const result = await uploader.uploadFolder(\n        './dist/assets',\n        '*.{png,jpg,gif}',  // Glob matching (optional)\n        true,               // Skip hidden files (optional)\n        's3'                // Storage override (optional)\n    );\n    \n    console.log(`Pushed ${result.succeeded}/${result.total_files} successfully.`);\n    if (result.failures.length > 0) {\n        console.warn(`Encountered ${result.failed} issues:`, result.failures);\n    }\n}\n\nbackupAssets();\n```\n\n**Response Structure:**\n\n```typescript\n{\n    source_folder: string;\n    results: UploadResult[];\n    failures: FolderUploadFailure[];\n    total_files: number;\n    succeeded: number;\n    failed: number;\n}\n```\n\n---\n\n### 3. Downloading Files\n\nFetch massive streams without crashing memory using built-in piping endpoints!\n\n```typescript\nasync function downloadAsset() {\n    const localPath = await uploader.downloadFile(\n        'file_abc123', \n        './downloads/file.jpg',\n        (downloaded, total) => {\n            const progress = ((downloaded / total) * 100).toFixed(1);\n            console.log(`Downloaded: ${progress}%`);\n        }\n    );\n    console.log(`File saved at: ${localPath}`);\n}\n\ndownloadAsset();\n```\n\n---\n\n### 4. Status Tracking & Interruption\n\nCheck or forcibly kill a multipart upload mid-execution:\n\n```typescript\n// Query upload status\nconst status = await uploader.getUploadStatus('upload_id_123');\nconsole.log(status);\n\n// Abort upload\nawait uploader.abortUpload('upload_id_123');\n```\n\n---\n\n## API Reference\n\n### CloudUploader Class\n\n#### Constructor\n\n```typescript\nconstructor(apiKey: string, options?: CloudUploaderOptions)\n```\n\n**Parameters:**\n- `apiKey` (string): Your CloudUploader API key (required)\n- `options` (CloudUploaderOptions): Configuration options (optional)\n\n#### Methods\n\n##### `uploadFile(filePath, progressCallback?, storageOverride?)`\n\nUpload a single file.\n\n```typescript\nuploadFile(\n    filePath: string,\n    progressCallback?: (uploadedBytes: number, totalBytes: number) => void,\n    storageOverride?: string\n): Promise<UploadResult>\n```\n\n##### `uploadFolder(folderPath, fileFilter?, skipHidden?, storageOverride?)`\n\nUpload entire folder with concurrency control.\n\n```typescript\nuploadFolder(\n    folderPath: string,\n    fileFilter?: string,\n    skipHidden?: boolean,\n    storageOverride?: string\n): Promise<FolderUploadResult>\n```\n\n##### `downloadFile(fileId, outputPath, progressCallback?)`\n\nDownload a file to local filesystem.\n\n```typescript\ndownloadFile(\n    fileId: string,\n    outputPath: string,\n    progressCallback?: (downloadedBytes: number, totalBytes: number) => void\n): Promise<string>\n```\n\n##### `getUploadStatus(uploadId)`\n\nGet status of an active upload.\n\n```typescript\ngetUploadStatus(uploadId: string): Promise<any>\n```\n\n##### `abortUpload(uploadId)`\n\nCancel an active multipart upload.\n\n```typescript\nabortUpload(uploadId: string): Promise<any>\n```\n\n##### `close()`\n\nClean up resources.\n\n```typescript\nclose(): void\n```\n\n---\n\n## Type Definitions\n\n### CloudUploaderOptions\n\n```typescript\ninterface CloudUploaderOptions {\n    baseUrl?: string;                  // API endpoint URL\n    timeout?: number;                  // Request timeout in ms\n    maxRetries?: number;               // Retry attempts\n    maxParallelUploads?: number;       // Concurrent upload limit\n    chunkSizeOverride?: number;        // Custom chunk size in bytes\n    storage?: string;                  // Storage backend (r2, s3, etc.)\n}\n```\n\n### UploadResult\n\n```typescript\ninterface UploadResult {\n    file_id: string;\n    storage_path: string;\n    size: number;\n    timestamp: string;\n}\n```\n\n### FolderUploadResult\n\n```typescript\ninterface FolderUploadResult {\n    source_folder: string;\n    results: UploadResult[];\n    failures: FolderUploadFailure[];\n    total_files: number;\n    succeeded: number;\n    failed: number;\n}\n```\n\n### FolderUploadFailure\n\n```typescript\ninterface FolderUploadFailure {\n    file_path: string;\n    error: string;\n}\n```\n\n---\n\n## Error Handling\n\nThe SDK provides specific error types for precise error handling:\n\n```typescript\nimport { \n    FileNotFoundError, \n    DownloadError,\n    AuthenticationError,\n    UploadFailedError \n} from '@clouduploader/clouduploader-js';\n\ntry {\n    await uploader.uploadFile('mission_critical.pdf');\n} catch (err) {\n    if (err instanceof FileNotFoundError) {\n        console.error(\"File does not exist locally:\", err.message);\n    } else if (err instanceof DownloadError) {\n        console.error(\"Download failed:\", err.message);\n    } else if (err instanceof AuthenticationError) {\n        console.error(\"Invalid API key. Check your credentials.\");\n    } else if (err instanceof UploadFailedError) {\n        console.error(\"Upload failed:\", err.message);\n    } else {\n        console.error(\"Unexpected error:\", err);\n    }\n}\n```\n\n### Available Error Types\n\n| Error | Description |\n|---|---|\n| `FileNotFoundError` | File or folder path does not exist |\n| `DownloadError` | Download operation failed |\n| `AuthenticationError` | Invalid or missing API credentials |\n| `UploadFailedError` | Upload operation encountered fatal error |\n\n---\n\n## Storage Backends\n\nThe SDK supports multiple cloud storage backends:\n\n| Backend | Code | Notes |\n|---|---|---|\n| Cloudflare R2 | `r2` | Default |\n| Amazon S3 | `s3` | AWS-compatible |\n| Azure Blob Storage | `azure` | Microsoft Cloud |\n| MinIO | `minio` | Self-hosted S3-compatible |\n| Google Cloud Storage | `gcs` | Google Cloud |\n\n---\n\n## Production Best Practices\n\n### 1. Environment Configuration\n\n```typescript\nconst uploader = new CloudUploader(\n    process.env.CLOUDUPLOADER_API_KEY!,\n    {\n        baseUrl: process.env.CLOUDUPLOADER_BASE_URL || 'http://localhost:8080',\n        maxParallelUploads: parseInt(process.env.MAX_PARALLEL_UPLOADS || '5'),\n        timeout: parseInt(process.env.REQUEST_TIMEOUT || '30000'),\n        maxRetries: parseInt(process.env.MAX_RETRIES || '3')\n    }\n);\n```\n\n### 2. Retry Logic\n\n```typescript\nasync function uploadWithRetry(filePath: string, maxAttempts = 3) {\n    for (let attempt = 1; attempt <= maxAttempts; attempt++) {\n        try {\n            return await uploader.uploadFile(filePath);\n        } catch (err) {\n            if (attempt === maxAttempts) throw err;\n            const delay = Math.pow(2, attempt - 1) * 1000;\n            console.log(`Retry attempt ${attempt} after ${delay}ms`);\n            await new Promise(r => setTimeout(r, delay));\n        }\n    }\n}\n```\n\n### 3. Resource Cleanup\n\n```typescript\nprocess.on('exit', () => {\n    uploader.close();\n});\n```\n\n---\n\n## Requirements\n\n- **Node.js**: >= 14.0.0\n- **npm**: >= 6.0.0\n- **TypeScript**: >= 4.0.0 (for TypeScript projects)\n\n---\n\n## Development\n\n### Setup\n\n```bash\ngit clone https://github.com/CloudUploader/clouduploader-js.git\ncd clouduploader-js\nnpm install\n```\n\n### Build\n\n```bash\nnpm run build\n```\n\n### Testing\n\n```bash\nnpm test\n```\n\n### Type Checking\n\n```bash\nnpx tsc --noEmit\n```\n\n---\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request to the [GitHub repository](https://github.com/CloudUploader/clouduploader-js).\n\n---\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n---\n\n## Support\n\nFor issues, questions, or feature requests, please open an issue on the [GitHub repository](https://github.com/CloudUploader/clouduploader-js/issues).\n\n### Resources\n\n- [GitHub Repository](https://github.com/CloudUploader/clouduploader-js)\n- [npm Package](https://www.npmjs.com/package/@clouduploader/clouduploader-js)\n- [HTTP Client](./src/httpClient.ts)\n- [Multipart Upload](./src/multipart.ts)\n\n---\n\n## Changelog\n\nSee [CHANGELOG](./CHANGELOG.md) for version history.\n\n---\n\n## Authors\n\n**CloudUploader Team**\n```\n","readmeFilename":"README.md"}