@koolbase/core 12.17.0 → 12.19.0

package/dist/esm/storage-transfer.js

@@ -32,6 +32,7 @@ export class KoolbaseUploadTask {
         this.cancelRequested = false;
         this.abortTransfer = null;
         this.total = 0;
+        this._uploadId = null;
         this._current = progressOf('pending', 0, 0);
         this.result = new Promise((res, rej) => {
             this.resolve = res;
@@ -45,6 +46,19 @@ export class KoolbaseUploadTask {
     get current() {
         return this._current;
     }
+    /**
+     * A large file's upload goes in parts, and can be resumed for a day: keep
+     * this id, and pass it to `KoolbaseStorage.resumeUpload` with the same
+     * file after the app restarts or the upload fails. Null for a file sent
+     * in one piece, and until the upload has begun.
+     */
+    get uploadId() {
+        return this._uploadId;
+    }
+    /** @internal */
+    setUploadId(id) {
+        this._uploadId = id;
+    }
     /**
      * Calls `listener` on every change of state and every chunk sent, starting
      * with where the upload is now. Returns a function that stops it.
@@ -139,70 +153,96 @@ export function runUploadTask(body) {
     return task;
 }
 /**
- * Sends `body` to a presigned `url` with PUT, reporting bytes as they are
- * sent. XMLHttpRequest where the host has it (browsers and React Native,
- * both report upload progress); fetch elsewhere, where progress jumps from
- * 0 to the total. A cancel aborts it.
+ * PUTs `body` to `url`, reporting bytes as they are sent. XMLHttpRequest
+ * where the host has it (browsers and React Native both report upload
+ * progress); fetch elsewhere, where progress jumps from 0 to the total.
+ * An aborted transfer rejects with `KoolbaseUploadCancelledError`.
  */
-export function putWithProgress(task, url, body, contentType) {
-    task.checkCancelled();
-    const total = body.size;
-    const report = (sent) => {
-        if (!task.cancelled)
-            task.emit('uploading', Math.min(sent, total));
-    };
-    report(0);
+export function transferBytes(url, body, contentType, onSent) {
     const XHR = globalThis.XMLHttpRequest;
     if (XHR) {
-        return new Promise((resolve, reject) => {
-            const xhr = new XHR();
-            let settled = false;
-            const done = (fn) => {
+        const xhr = new XHR();
+        let settled = false;
+        let fail = () => undefined;
+        const done = new Promise((resolve, reject) => {
+            const finish = (fn) => {
                 if (settled)
                     return;
                 settled = true;
-                task.setAbort(null);
                 fn();
             };
+            fail = (e) => finish(() => reject(e));
             xhr.open('PUT', url);
-            xhr.setRequestHeader('Content-Type', contentType);
+            if (contentType)
+                xhr.setRequestHeader('Content-Type', contentType);
             if (xhr.upload) {
-                xhr.upload.onprogress = (ev) => report(ev.loaded);
+                xhr.upload.onprogress = (ev) => onSent(Math.min(ev.loaded, body.size));
             }
-            xhr.onload = () => done(() => {
-                if (task.cancelled)
-                    return reject(new KoolbaseUploadCancelledError());
-                resolve({ status: xhr.status, etag: xhr.getResponseHeader('etag') ?? '' });
-            });
-            xhr.onerror = () => done(() => reject(task.cancelled ? new KoolbaseUploadCancelledError() : new KoolbaseNetworkError(url, new Error('the upload did not complete'))));
-            xhr.onabort = () => done(() => reject(new KoolbaseUploadCancelledError()));
-            task.setAbort(() => {
-                xhr.abort();
-                // Some hosts do not fire onabort for an aborted send.
-                done(() => reject(new KoolbaseUploadCancelledError()));
-            });
+            xhr.onload = () => finish(() => resolve({ status: xhr.status, etag: xhr.getResponseHeader('etag') ?? '' }));
+            xhr.onerror = () => fail(new KoolbaseNetworkError(url, new Error('the upload did not complete')));
+            xhr.onabort = () => fail(new KoolbaseUploadCancelledError());
+            onSent(0);
             xhr.send(body);
         });
+        return {
+            done,
+            abort: () => {
+                xhr.abort();
+                // Some hosts do not fire onabort for an aborted send.
+                fail(new KoolbaseUploadCancelledError());
+            },
+        };
     }
     const controller = typeof AbortController !== 'undefined' ? new AbortController() : null;
-    task.setAbort(() => controller?.abort());
-    return fetch(url, {
+    let aborted = false;
+    onSent(0);
+    const done = fetch(url, {
         method: 'PUT',
-        headers: { 'Content-Type': contentType },
+        headers: contentType ? { 'Content-Type': contentType } : {},
         body,
         signal: controller?.signal,
     })
         .then((res) => {
-        task.checkCancelled();
+        if (aborted)
+            throw new KoolbaseUploadCancelledError();
+        onSent(body.size);
         return { status: res.status, etag: res.headers.get('etag') ?? '' };
     })
         .catch((e) => {
-        if (task.cancelled || e?.name === 'AbortError') {
+        if (aborted || e?.name === 'AbortError')
             throw new KoolbaseUploadCancelledError();
-        }
         if (e instanceof KoolbaseStorageError)
             throw e;
         throw new KoolbaseNetworkError(url, e);
+    });
+    return {
+        done,
+        abort: () => {
+            aborted = true;
+            controller?.abort();
+        },
+    };
+}
+/**
+ * Sends `body` to a presigned `url` with PUT as the task's one transfer,
+ * reporting bytes as they are sent; a cancel aborts it.
+ */
+export function putWithProgress(task, url, body, contentType) {
+    task.checkCancelled();
+    const total = body.size;
+    const report = (sent) => {
+        if (!task.cancelled)
+            task.emit('uploading', Math.min(sent, total));
+    };
+    const t = transferBytes(url, body, contentType, report);
+    task.setAbort(() => t.abort());
+    return t.done
+        .then((r) => {
+        task.checkCancelled();
+        return r;
+    })
+        .catch((e) => {
+        throw task.cancelled ? new KoolbaseUploadCancelledError() : e;
     })
         .finally(() => task.setAbort(null));
 }

package/dist/esm/storage.d.ts

@@ -72,6 +72,46 @@ export declare class KoolbaseStorage {
      */
     startUpload(options: UploadOptions): KoolbaseUploadTask;
     private runUpload;
+    /**
+     * Files larger than this go up in parts (S3): each part retried on its
+     * own, the upload resumable for a day with `resumeUpload`. 16 MiB.
+     */
+    static multipartThreshold: number;
+    /**
+     * Resumes a large file's upload that failed or was interrupted -- the
+     * network dropped, the app was closed -- sending only the parts that did
+     * not arrive. `uploadId` is the failed task's `uploadId`; `file` must be
+     * the same file. Within a day of the upload beginning.
+     *
+     * @example
+     * const task = Koolbase.storage.startUpload({ bucket: 'video', path: 'talk.mp4', file });
+     * saveForLater(task.uploadId); // once the upload has begun
+     * // ... after a restart:
+     * await Koolbase.storage.resumeUpload({ bucket: 'video', uploadId, file }).result;
+     */
+    resumeUpload(options: {
+        bucket: string;
+        uploadId: string;
+        file: UploadOptions['file'];
+        metadata?: Record<string, string>;
+        overwrite?: boolean;
+    }): KoolbaseUploadTask;
+    private runInParts;
+    /**
+     * Downloads a file's bytes, reporting them as they arrive (S3):
+     * `onProgress(received, total)`, total null when the size is not known.
+     * Aborting `signal` stops it with `KoolbaseDownloadCancelledError`.
+     *
+     * @example
+     * const blob = await Koolbase.storage.download({ bucket: 'video', path: 'talk.mp4', onProgress: (r, t) => setPct(t ? r / t : 0) });
+     */
+    download(options: {
+        bucket: string;
+        path: string;
+        versionId?: string;
+        onProgress?: (received: number, total: number | null) => void;
+        signal?: AbortSignal;
+    }): Promise<Blob>;
     /**
      * One page of a bucket's files. The bucket's view rule is applied to every
      * file: the page holds only files the signed-in person may view. Pass the

package/dist/esm/storage.js

@@ -3,7 +3,16 @@ import { sessionFetch } from './network.js';
 import { KoolbaseUnauthenticatedError } from './errors.js';
 import { KoolbaseStorageError, koolbaseStorageErrorFromResponse, } from './storage-errors.js';
 import { putWithProgress, runUploadTask } from './storage-transfer.js';
+import { sendParts } from './storage-multipart.js';
+import { KoolbaseDownloadCancelledError } from './storage-errors.js';
+import { refreshBucketFiles } from './files-refresh.js';
+import { KoolbaseNetworkError } from './network.js';
 import { fileInfoFromJson, filePageFromJson, listFilesQuery, } from './storage-files.js';
+/** An upload task whose success reloads the bucket's file lists (storage S4). */
+function listsReload(task, bucket) {
+    task.result.then(() => { void refreshBucketFiles(bucket); }, () => { });
+    return task;
+}
 // --- Cloudflare image-transform URL helpers -------------------------------
 // Module-private — callers use KoolbaseStorage.publicUrl / publicUrlForObject.
 function clampInt(v, min, max) {
@@ -126,7 +135,7 @@ export class KoolbaseStorage {
      * const { object } = await task.result;
      */
     startUpload(options) {
-        return runUploadTask((task) => this.runUpload(options, task));
+        return listsReload(runUploadTask((task) => this.runUpload(options, task)), options.bucket);
     }
     async runUpload(options, task) {
         task.checkCancelled();
@@ -141,6 +150,19 @@ export class KoolbaseStorage {
             : options.file.type;
         if (isBlob)
             task.setTotal(options.file.size);
+        // A browser hands us the bytes already: a File from an input is a Blob,
+        // and fetching its .uri would be fetching undefined. React Native hands
+        // us a local URI, and its fetch resolves that into a Blob -- read first,
+        // since its size decides how it is sent (S3).
+        const fileBlob = isBlob
+            ? options.file
+            : await (await sessionFetch(options.file.uri)).blob();
+        task.setTotal(fileBlob.size);
+        task.checkCancelled();
+        // Large files go in parts: resumable, each part retried (S3).
+        if (fileBlob.size > KoolbaseStorage.multipartThreshold) {
+            return this.runInParts(options.bucket, options, task, fileBlob, contentType, null);
+        }
         // ─── Step 1: Get presigned upload URL ───
         const urlRes = await sessionFetch(`${this.config.baseUrl}/v1/sdk/storage/upload-url`, {
             method: 'POST',
@@ -162,16 +184,7 @@ export class KoolbaseStorage {
         task.checkCancelled();
         // ─── Step 2: Upload directly to R2 ───
         // R2 presigned URLs expect raw binary, NOT multipart/form-data.
-        //
-        // A browser hands us the bytes already: a File from an input is a Blob,
-        // and fetching its .uri would be fetching undefined. React Native hands
-        // us a local URI, and its fetch resolves that into a Blob — which is why
-        // the two hosts differ here and nowhere else in this method.
-        const fileBlob = isBlob
-            ? options.file
-            : await (await sessionFetch(options.file.uri)).blob();
         const fileSize = fileBlob.size;
-        task.setTotal(fileSize);
         const uploadRes = await putWithProgress(task, upload_url, fileBlob, contentType);
         if (uploadRes.status < 200 || uploadRes.status >= 300) {
             // R2 PUT errors don't follow the Koolbase error shape — surface as a
@@ -219,6 +232,173 @@ export class KoolbaseStorage {
         const downloadUrl = await this.getDownloadUrl(options.bucket, options.path);
         return { object, downloadUrl };
     }
+    /**
+     * Resumes a large file's upload that failed or was interrupted -- the
+     * network dropped, the app was closed -- sending only the parts that did
+     * not arrive. `uploadId` is the failed task's `uploadId`; `file` must be
+     * the same file. Within a day of the upload beginning.
+     *
+     * @example
+     * const task = Koolbase.storage.startUpload({ bucket: 'video', path: 'talk.mp4', file });
+     * saveForLater(task.uploadId); // once the upload has begun
+     * // ... after a restart:
+     * await Koolbase.storage.resumeUpload({ bucket: 'video', uploadId, file }).result;
+     */
+    resumeUpload(options) {
+        return listsReload(runUploadTask(async (task) => {
+            const isBlob = typeof Blob !== 'undefined' && options.file instanceof Blob;
+            const blob = isBlob
+                ? options.file
+                : await (await sessionFetch(options.file.uri)).blob();
+            task.setTotal(blob.size);
+            return this.runInParts(options.bucket, options, task, blob, '', options.uploadId);
+        }), options.bucket);
+    }
+    async runInParts(bucket, options, task, file, contentType, resumeId) {
+        const base = `${this.config.baseUrl}/v1/sdk/storage/uploads`;
+        const json = async () => ({ ...(await this.buildHeaders()), 'Content-Type': 'application/json' });
+        const overwrite = options.overwrite ?? false;
+        let plan;
+        if (resumeId) {
+            const res = await sessionFetch(`${base}?bucket=${encodeURIComponent(bucket)}&upload_id=${encodeURIComponent(resumeId)}`, {
+                headers: await this.buildHeaders(),
+            });
+            if (!res.ok)
+                throw await this.error(res, 'Failed to resume the upload');
+            plan = (await res.json());
+            if (plan.size !== file.size) {
+                throw new KoolbaseStorageError(`This is not the file the upload began with: it has ${file.size} bytes, the upload ${plan.size}`, 'validation_error');
+            }
+        }
+        else {
+            const res = await sessionFetch(base, {
+                method: 'POST',
+                headers: await json(),
+                body: JSON.stringify({ bucket, path: options.path, content_type: contentType, size: file.size, overwrite }),
+            });
+            if (!res.ok)
+                throw await this.error(res, 'Failed to begin the upload');
+            plan = (await res.json());
+        }
+        task.setUploadId(plan.upload_id);
+        task.checkCancelled();
+        await sendParts(task, plan, file, {
+            links: async (parts) => {
+                const res = await sessionFetch(`${base}/parts`, {
+                    method: 'POST',
+                    headers: await json(),
+                    body: JSON.stringify({ bucket, upload_id: plan.upload_id, parts }),
+                });
+                if (!res.ok)
+                    throw await this.error(res, 'Failed to get upload links');
+                return (await res.json()).links;
+            },
+            abort: async () => {
+                await sessionFetch(base, {
+                    method: 'DELETE',
+                    headers: await json(),
+                    body: JSON.stringify({ bucket, upload_id: plan.upload_id }),
+                });
+            },
+        });
+        // The parts have arrived: the server joins and checks them. No longer
+        // cancellable.
+        task.verifying();
+        const body = { bucket, upload_id: plan.upload_id, overwrite };
+        if (options.metadata !== undefined)
+            body.metadata = options.metadata;
+        const done = await sessionFetch(`${base}/complete`, { method: 'POST', headers: await json(), body: JSON.stringify(body) });
+        if (!done.ok)
+            throw await this.error(done, 'Failed to complete the upload');
+        const object = mapObjectFromServer(await done.json());
+        const downloadUrl = await this.getDownloadUrl(bucket, object.path);
+        return { object, downloadUrl };
+    }
+    /**
+     * Downloads a file's bytes, reporting them as they arrive (S3):
+     * `onProgress(received, total)`, total null when the size is not known.
+     * Aborting `signal` stops it with `KoolbaseDownloadCancelledError`.
+     *
+     * @example
+     * const blob = await Koolbase.storage.download({ bucket: 'video', path: 'talk.mp4', onProgress: (r, t) => setPct(t ? r / t : 0) });
+     */
+    async download(options) {
+        if (options.signal?.aborted)
+            throw new KoolbaseDownloadCancelledError();
+        const url = await this.getDownloadUrl(options.bucket, options.path, options.versionId);
+        const report = options.onProgress ?? (() => undefined);
+        const XHR = globalThis.XMLHttpRequest;
+        if (XHR) {
+            return new Promise((resolve, reject) => {
+                const xhr = new XHR();
+                let settled = false;
+                const finish = (fn) => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    options.signal?.removeEventListener('abort', stop);
+                    fn();
+                };
+                const stop = () => {
+                    xhr.abort();
+                    finish(() => reject(new KoolbaseDownloadCancelledError()));
+                };
+                options.signal?.addEventListener('abort', stop);
+                xhr.open('GET', url);
+                xhr.responseType = 'blob';
+                xhr.onprogress = (ev) => report(ev.loaded, ev.lengthComputable ? ev.total : null);
+                xhr.onload = () => finish(() => {
+                    if (xhr.status < 200 || xhr.status >= 300) {
+                        reject(new KoolbaseStorageError(`Download failed: ${xhr.status}`));
+                        return;
+                    }
+                    const blob = xhr.response;
+                    report(blob.size, blob.size);
+                    resolve(blob);
+                });
+                xhr.onerror = () => finish(() => reject(new KoolbaseNetworkError(url, new Error('the download did not complete'))));
+                xhr.onabort = () => finish(() => reject(new KoolbaseDownloadCancelledError()));
+                xhr.send();
+            });
+        }
+        let res;
+        try {
+            res = await fetch(url, { signal: options.signal });
+        }
+        catch (e) {
+            if (options.signal?.aborted)
+                throw new KoolbaseDownloadCancelledError();
+            throw new KoolbaseNetworkError(url, e);
+        }
+        if (!res.ok)
+            throw new KoolbaseStorageError(`Download failed: ${res.status}`);
+        const total = Number(res.headers.get('content-length')) || null;
+        const reader = res.body?.getReader?.();
+        if (!reader) {
+            const blob = await res.blob();
+            report(blob.size, blob.size);
+            return blob;
+        }
+        const chunks = [];
+        let received = 0;
+        report(0, total);
+        try {
+            for (;;) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                chunks.push(value);
+                received += value.length;
+                report(received, total);
+            }
+        }
+        catch (e) {
+            if (options.signal?.aborted)
+                throw new KoolbaseDownloadCancelledError();
+            throw new KoolbaseNetworkError(url, e);
+        }
+        return new Blob(chunks, { type: res.headers.get('content-type') ?? '' });
+    }
     /**
      * One page of a bucket's files. The bucket's view rule is applied to every
      * file: the page holds only files the signed-in person may view. Pass the
@@ -289,7 +469,9 @@ export class KoolbaseStorage {
         if (!res.ok) {
             throw await this.error(res, op === 'move' ? 'Failed to move the file' : 'Failed to copy the file');
         }
-        return mapObjectFromServer(await res.json());
+        const moved = mapObjectFromServer(await res.json());
+        void refreshBucketFiles(o.bucket, ...(o.toBucket && o.toBucket !== o.bucket ? [o.toBucket] : []));
+        return moved;
     }
     /**
      * Apply a partial metadata update to an existing object. Returns the
@@ -337,6 +519,7 @@ export class KoolbaseStorage {
             throw await this.error(res, 'Failed to update metadata');
         }
         const raw = await res.json();
+        void refreshBucketFiles(bucket);
         return mapObjectFromServer(raw);
     }
     /**
@@ -468,11 +651,11 @@ export class KoolbaseStorage {
             },
             body: JSON.stringify({ bucket, path }),
         });
-        if (res.status === 204)
+        if (res.ok) {
+            void refreshBucketFiles(bucket);
             return;
-        if (!res.ok) {
-            throw await this.error(res, 'Failed to delete file');
         }
+        throw await this.error(res, 'Failed to delete file');
     }
     /**
      * List all versions of a file path, newest-first. Returns a flat list
@@ -529,7 +712,9 @@ export class KoolbaseStorage {
         if (!res.ok) {
             throw await this.error(res, 'Failed to restore version');
         }
-        return mapObjectFromServer(await res.json());
+        const restored = mapObjectFromServer(await res.json());
+        void refreshBucketFiles(bucket);
+        return restored;
     }
     /**
      * Hard-remove a single history version — both the metadata row and
@@ -551,6 +736,11 @@ export class KoolbaseStorage {
         }
     }
 }
+/**
+ * Files larger than this go up in parts (S3): each part retried on its
+ * own, the upload resumable for a day with `resumeUpload`. 16 MiB.
+ */
+KoolbaseStorage.multipartThreshold = 16 * 1024 * 1024;
 /**
  * Maps the snake_case server JSON to the camelCase {@link KoolbaseObject}.
  * Defensive: missing or null `metadata` (older / non-Koolbase responses)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@koolbase/core",
-  "version": "12.17.0",
+  "version": "12.19.0",
   "description": "Koolbase SDK core \u2014 shared behaviour behind @koolbase/react-native and @koolbase/js. Install one of those, not this.",
   "main": "./dist/cjs/index.js",
   "types": "./dist/esm/index.d.ts",