rdash-sdk 0.0.6

package/README.md

@@ -0,0 +1,119 @@
+# rdash-sdk
+
+Official JavaScript SDK for rdash — chunked uploads, and more.
+
+## Features
+
+- **ChunkUpload** — parallel chunked file uploads with retries and progress tracking
+
+## Install
+
+```bash
+npm install rdash-sdk
+```
+
+## Quick Start
+
+### Browser
+
+```js
+import { ChunkedUploader } from "rdash-sdk";
+
+const uploader = new ChunkedUploader({
+  backendBaseUrl: "https://api.rdash.io/v1/core",
+  authToken: "your_token",
+});
+
+const url = await uploader.upload(
+  file, // File or Blob
+  { path: "invoice-file" },
+  (progress) => console.log(`${progress}%`)
+);
+```
+
+### Node.js
+
+```js
+import { ChunkedUploader } from "rdash-sdk";
+import { readFile } from "node:fs/promises";
+
+const uploader = new ChunkedUploader({
+  backendBaseUrl: "https://api.rdash.io/v1/core",
+  authToken: "your_token",
+});
+
+const buffer = await readFile("./report.pdf");
+const blob = new Blob([buffer], { type: "application/pdf" });
+
+const url = await uploader.upload(blob, { path: "reports" });
+```
+
+### Subpath Import
+
+You can also import features directly:
+
+```js
+import { ChunkedUploader } from "rdash-sdk/ChunkUpload";
+```
+
+## Config Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `backendBaseUrl` | `string` | *required* | Base URL for the upload API |
+| `multipleUpload` | `number` | `3` | Parallel chunk uploads (1-6) |
+| `authToken` | `string \| null` | `null` | Bearer token for authentication |
+| `keepAlive` | `boolean` | `true` | Use HTTP keep-alive |
+| `chunkTimeout` | `number` | `30000` | Timeout per chunk in milliseconds |
+
+## API
+
+### `upload(fileOrUrl, options, onProgress?)`
+
+Main method. Accepts a `File`, `Blob`, or URL string. Downloads URL inputs automatically, splits the file into chunks, uploads in parallel, and returns the final upload path.
+
+```js
+const path = await uploader.upload(file, { path: "documents" }, (pct) => {});
+```
+
+### `startUpload(file, options)`
+
+Initiates a chunked upload session with the backend. Returns upload metadata including part URLs.
+
+```js
+const uploadInfo = await uploader.startUpload(file, { path: "documents" });
+```
+
+### `uploadChunks(file, uploadInfo, onProgress?)`
+
+Uploads all chunks in parallel with automatic retries (up to 3 attempts per chunk with exponential backoff). Returns an array of part ETags.
+
+```js
+const etags = await uploader.uploadChunks(file, uploadInfo, (pct) => {});
+```
+
+### `completeUpload(upload_id, object_key, etags)`
+
+Finalizes the multipart upload after all chunks are uploaded.
+
+```js
+const result = await uploader.completeUpload(uploadId, objectKey, etags);
+```
+
+## Progress Tracking
+
+The `onProgress` callback receives a number from 0-100 representing the upload percentage. Updates are throttled to ~20 reports per upload to avoid excessive callbacks.
+
+```js
+await uploader.upload(file, { path: "data" }, (progress) => {
+  progressBar.style.width = `${progress}%`;
+  progressLabel.textContent = `${progress}%`;
+});
+```
+
+## Node.js Compatibility
+
+- **Node 18+**: Supported via `Blob`. Pass a `Blob` constructed from a `Buffer`.
+- **Node 20+**: Full support including `File` objects and URL-to-file downloads.
+
+The `fetch` API is available globally in Node 18+, which this library relies on. No polyfills are needed.

package/chunk-uploader/index.d.ts

@@ -0,0 +1,29 @@
+export interface ChunkedUploaderConfig {
+    /** Base URL for the upload API */
+    backendBaseUrl: string;
+    /** Number of parallel chunks to upload (max 6, default 3) */
+    multipleUpload?: number;
+    /** Authentication token */
+    authToken?: string | null;
+    /** Use HTTP keep-alive (default true) */
+    keepAlive?: boolean;
+    /** Timeout per chunk in milliseconds (default 30000) */
+    chunkTimeout?: number;
+}
+
+export interface UploadOptions {
+    /** Upload path */
+    path: string;
+}
+
+export type ProgressCallback = (progress: number) => void;
+
+export declare class ChunkedUploader {
+    constructor(config: ChunkedUploaderConfig);
+
+    upload(
+        fileOrUrl: File | Blob | string,
+        options: UploadOptions,
+        onProgress?: ProgressCallback
+    ): Promise<string>;
+}

package/chunk-uploader/index.js

@@ -0,0 +1,280 @@
+/**
+ * ChunkedUploader.js
+ * Usage:
+ *   const uploader = new ChunkedUploader({ backendBaseUrl: "https://api.rdash.io/v1/core", authToken: "token_here" });
+ *   uploader.upload(file, { path: "invoice-file" }, progress => console.log(progress)).then(url => ...)
+ */
+
+/**
+ * @typedef {Object} ChunkedUploaderConfig
+ * @property {string} backendBaseUrl - Base URL for the upload API
+ * @property {number} [multipleUpload=3] - Number of parallel chunks to upload (max 6)
+ * @property {string|null} [authToken=null] - Authentication token
+ * @property {boolean} [keepAlive=true] - Use HTTP keep-alive
+ * @property {number} [chunkTimeout=30000] - Timeout per chunk in milliseconds
+ */
+
+/**
+ * @typedef {Object} UploadOptions
+ * @property {string} path - Upload path
+ */
+
+/**
+ * @typedef {function(number): void} ProgressCallback
+ */
+
+/**
+ * @typedef {Object} ChunkInfo
+ * @property {number} partNumber
+ * @property {string} eTag
+ * @property {string} status
+ * @property {string} url
+ * @property {number} retry
+ * @property {number} size
+ */
+
+export class ChunkedUploader {
+  constructor({ backendBaseUrl, multipleUpload = 3, authToken = null, keepAlive = true, chunkTimeout = 30000 }) {
+    this.backendBaseUrl = backendBaseUrl.replace(/\/+$/, ""); // remove trailing slash
+    this.multipleUpload = Math.min(Math.max(multipleUpload, 1), 6);
+    this.authToken = authToken;
+    this.chunkTimeout = chunkTimeout;
+
+    this._cachedHeaders = this._buildHeaders();
+
+    this.fetchOptions = {
+      keepalive: keepAlive,
+    };
+  }
+
+  _buildHeaders() {
+    const headers = { "Content-Type": "application/json" };
+    if (this.authToken) {
+      headers["Authorization"] = `Bearer ${this.authToken}`;
+    }
+    return headers;
+  }
+
+  get _headers() {
+    return this._cachedHeaders;
+  }
+
+  async _downloadUrlToFile(url) {
+    const filename = url.split("/").pop()?.split("?")[0] || "downloaded_file";
+
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.chunkTimeout);
+
+    try {
+      const resp = await fetch(url, {
+        signal: controller.signal,
+        ...this.fetchOptions,
+      });
+      clearTimeout(timeoutId);
+
+      if (!resp.ok) throw new Error(`Failed to download file from URL: ${resp.status}`);
+
+      const blob = await resp.blob();
+      return new File([blob], filename, { type: blob.type });
+    } catch (error) {
+      clearTimeout(timeoutId);
+      throw error;
+    }
+  }
+
+  async startUpload(file, { path }) {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.chunkTimeout);
+
+    try {
+      const headers = {
+        ...this.fetchOptions.headers,
+        ...this._headers,
+      };
+
+      const resp = await fetch(`${this.backendBaseUrl}/file-upload/initiate`, {
+        method: "POST",
+        headers,
+        body: JSON.stringify({
+          file_name: file.name || "upload",
+          file_size: file.size,
+          path,
+        }),
+        signal: controller.signal,
+        keepalive: this.fetchOptions.keepalive,
+      });
+
+      clearTimeout(timeoutId);
+
+      if (!resp.ok) throw new Error(`Failed to initiate upload: ${resp.status}`);
+      return await resp.json();
+    } catch (error) {
+      clearTimeout(timeoutId);
+      throw error;
+    }
+  }
+
+  async uploadChunks(file, uploadInfo, onProgress) {
+    const parts = uploadInfo.data ? uploadInfo.data.parts : uploadInfo.parts;
+    const totalChunks = parts.length;
+    const fileSize = file.size;
+    const chunkSize = Math.ceil(fileSize / totalChunks);
+
+    const chunkProgress = new Map();
+    const isLargeFile = fileSize > 100 * 1024 * 1024;
+    const effectiveParallelism = isLargeFile ? Math.min(this.multipleUpload, 2) : this.multipleUpload;
+
+    /** @type {ChunkInfo[]} */
+    const chunkInfo = parts.map((part, i) => ({
+      partNumber: i,
+      eTag: "",
+      status: "not-started",
+      url: part.part_url || part.partUrl,
+      retry: 0,
+      size: 0,
+    }));
+
+    let completed = 0;
+    let progressUpdateCount = 0;
+    const maxRetries = 3;
+
+    const uploadChunk = async (chunkNumber) => {
+      const chunk = chunkInfo[chunkNumber];
+      const start = chunkNumber * chunkSize;
+      const end = Math.min(fileSize, (chunkNumber + 1) * chunkSize);
+
+      for (let attempt = 0; attempt < maxRetries; attempt++) {
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), this.chunkTimeout);
+
+        try {
+          chunk.status = "in-progress";
+          chunk.retry = attempt;
+          const payload = file.slice(start, end);
+          chunk.size = payload.size;
+
+          const res = await fetch(chunk.url, {
+            method: "PUT",
+            body: payload,
+            signal: controller.signal,
+            keepalive: this.fetchOptions.keepalive,
+          });
+
+          clearTimeout(timeoutId);
+
+          if (!res.ok) throw new Error(`HTTP ${res.status}: Failed chunk ${chunkNumber + 1}`);
+
+          chunk.status = "completed";
+          chunk.eTag = (res.headers.get("etag") || "").replace(/"/g, "");
+
+          chunkProgress.set(chunkNumber, payload.size);
+          completed++;
+
+          const shouldUpdateProgress = onProgress && (
+            completed === totalChunks ||
+            ++progressUpdateCount % Math.max(1, Math.ceil(totalChunks / 20)) === 0
+          );
+
+          if (shouldUpdateProgress) {
+            const loaded = Array.from(chunkProgress.values()).reduce((a, b) => a + b, 0);
+            onProgress(Math.round((loaded * 100) / fileSize));
+          }
+
+          return {
+            part_number: chunkNumber + 1,
+            part_e_tag: chunk.eTag,
+          };
+        } catch (err) {
+          clearTimeout(timeoutId);
+          chunk.status = attempt < maxRetries - 1 ? "retrying" : "failed";
+
+          if (attempt === maxRetries - 1) {
+            throw new Error(`Chunk ${chunkNumber + 1} failed after ${maxRetries} attempts: ${err.message}`);
+          }
+
+          const delay = Math.pow(2, attempt) * 1000 + Math.random() * 1000;
+          await new Promise((resolve) => setTimeout(resolve, delay));
+        }
+      }
+    };
+
+    const results = new Array(totalChunks);
+    const workers = [];
+    let nextChunkIndex = 0;
+
+    for (let i = 0; i < Math.min(effectiveParallelism, totalChunks); i++) {
+      workers.push(
+        (async () => {
+          while (nextChunkIndex < totalChunks) {
+            const chunkIndex = nextChunkIndex++;
+            results[chunkIndex] = await uploadChunk(chunkIndex);
+          }
+        })()
+      );
+    }
+
+    await Promise.all(workers);
+
+    const failedChunks = chunkInfo.filter((chunk) => chunk.status !== "completed");
+    if (failedChunks.length > 0) {
+      throw new Error(`${failedChunks.length} chunks failed to upload`);
+    }
+
+    return results;
+  }
+
+  async completeUpload(upload_id, object_key, etags) {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.chunkTimeout);
+
+    try {
+      const headers = {
+        ...this.fetchOptions.headers,
+        ...this._headers,
+      };
+
+      const res = await fetch(`${this.backendBaseUrl}/file-upload/complete`, {
+        method: "POST",
+        headers,
+        body: JSON.stringify({ upload_id, object_key, parts: etags }),
+        signal: controller.signal,
+        keepalive: this.fetchOptions.keepalive,
+      });
+
+      clearTimeout(timeoutId);
+
+      if (!res.ok) throw new Error(`Failed to complete upload: ${res.status}`);
+      return await res.json();
+    } catch (error) {
+      clearTimeout(timeoutId);
+      throw error;
+    }
+  }
+
+  async upload(fileOrUrl, { path }, onProgress) {
+    let fileObj = fileOrUrl;
+
+    if (typeof fileOrUrl === "string" && fileOrUrl.startsWith("http")) {
+      fileObj = await this._downloadUrlToFile(fileOrUrl);
+    }
+
+    if (!fileObj || typeof fileObj.size !== "number") {
+      throw new Error("Invalid file object provided");
+    }
+
+    try {
+      const uploadInfo = await this.startUpload(fileObj, { path });
+      const etags = await this.uploadChunks(fileObj, uploadInfo, onProgress);
+
+      const finalResult = await this.completeUpload(
+        uploadInfo.data ? uploadInfo.data.upload_id : uploadInfo.upload_id,
+        uploadInfo.data ? uploadInfo.data.object_key : uploadInfo.object_key,
+        etags
+      );
+
+      return finalResult.data ? finalResult.data.path : finalResult.path;
+    } catch (error) {
+      throw new Error(`Upload failed: ${error.message}`);
+    }
+  }
+}

package/index.d.ts

@@ -0,0 +1 @@
+export * from "./chunk-uploader/index.d.ts";

package/index.js

@@ -0,0 +1 @@
+export { ChunkedUploader } from "./chunk-uploader/index.js";

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "rdash-sdk",
+  "version": "0.0.6",
+  "description": "Official JavaScript SDK for rdash — chunked uploads, and more",
+  "type": "module",
+  "main": "./index.js",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.js"
+    },
+    "./ChunkUpload": {
+      "types": "./chunk-uploader/index.d.ts",
+      "import": "./chunk-uploader/index.js"
+    }
+  },
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "chunk-uploader/**"
+  ],
+  "keywords": ["rdash", "sdk", "upload", "chunk-uploader"],
+  "license": "MIT",
+  "scripts": {},
+  "engines": { "node": ">=18.0.0" },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rdash-tech/rdash-sdk.git"
+  }
+}