@koolbase/core 12.14.0 → 12.16.0

package/dist/esm/storage.d.ts

@@ -1,4 +1,6 @@
 import { KoolbaseConfig, UploadOptions, UploadResult, KoolbaseObject, KoolbaseObjectVersion, KoolbaseImageTransform } from './types.js';
+import { KoolbaseUploadTask } from './storage-transfer.js';
+import { KoolbaseFileInfo, KoolbaseFilePage, ListFilesOptions } from './storage-files.js';
 /**
  * Koolbase storage client — uploads, downloads, and deletes via presigned
  * Cloudflare R2 URLs.
@@ -53,6 +55,45 @@ export declare class KoolbaseStorage {
      * overwriting silently, pass `overwrite: true` explicitly.
      */
     upload(options: UploadOptions): Promise<UploadResult>;
+    /**
+     * Starts an upload you can follow and cancel: the same upload as
+     * {@link upload}, returned at once as a {@link KoolbaseUploadTask}.
+     *
+     * The task goes pending -> uploading (bytes sent of total) -> verifying
+     * -> completed, or failed / cancelled. `cancel()` stops it until the
+     * server begins checking the bytes (verifying); nothing is stored. Only
+     * completed means the file can be referenced from a record.
+     *
+     * @example
+     * const task = Koolbase.storage.startUpload({ bucket: 'posters', path: 'gig.png', file });
+     * const stop = task.onProgress((p) => setPercent(Math.round(p.fraction * 100)));
+     * cancelButton.onclick = () => task.cancel();
+     * const { object } = await task.result;
+     */
+    startUpload(options: UploadOptions): KoolbaseUploadTask;
+    private runUpload;
+    /**
+     * 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
+     * page's `nextCursor` back as `cursor` for the next one; a page can hold
+     * fewer files than `limit` and still have a next.
+     *
+     * @example
+     * let cursor: string | undefined;
+     * do {
+     *   const page = await Koolbase.storage.listFiles({ bucket: 'posters', prefix: 'events/', cursor });
+     *   show(page.files);
+     *   cursor = page.nextCursor ?? undefined;
+     * } while (cursor);
+     */
+    listFiles(options: ListFilesOptions): Promise<KoolbaseFilePage>;
+    /**
+     * One file's details -- size, type, metadata, who uploaded it, and its
+     * permanent link while its bucket is public. Throws
+     * `KoolbaseStorageNotFoundError` for a file that is not there or that
+     * the bucket's view rule hides from the caller.
+     */
+    getFileInfo(bucket: string, path: string): Promise<KoolbaseFileInfo>;
     /**
      * Apply a partial metadata update to an existing object. Returns the
      * post-update {@link KoolbaseObject} with the merged metadata.

package/dist/esm/storage.js

@@ -1,7 +1,9 @@
 import { KoolbaseStorageProjectIdentityError } from './storage-errors.js';
-import { koolbaseFetch } from './network.js';
+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 { fileInfoFromJson, filePageFromJson, listFilesQuery, } from './storage-files.js';
 // --- Cloudflare image-transform URL helpers -------------------------------
 // Module-private — callers use KoolbaseStorage.publicUrl / publicUrlForObject.
 function clampInt(v, min, max) {
@@ -88,6 +90,46 @@ export class KoolbaseStorage {
      * overwriting silently, pass `overwrite: true` explicitly.
      */
     async upload(options) {
+        const task = this.startUpload(options);
+        const signal = options.signal;
+        const onAbort = () => task.cancel();
+        if (signal) {
+            if (signal.aborted)
+                task.cancel();
+            else
+                signal.addEventListener('abort', onAbort);
+        }
+        const stop = options.onProgress
+            ? task.onProgress((p) => options.onProgress?.(Math.round(p.fraction * 100), p))
+            : null;
+        try {
+            return await task.result;
+        }
+        finally {
+            stop?.();
+            signal?.removeEventListener('abort', onAbort);
+        }
+    }
+    /**
+     * Starts an upload you can follow and cancel: the same upload as
+     * {@link upload}, returned at once as a {@link KoolbaseUploadTask}.
+     *
+     * The task goes pending -> uploading (bytes sent of total) -> verifying
+     * -> completed, or failed / cancelled. `cancel()` stops it until the
+     * server begins checking the bytes (verifying); nothing is stored. Only
+     * completed means the file can be referenced from a record.
+     *
+     * @example
+     * const task = Koolbase.storage.startUpload({ bucket: 'posters', path: 'gig.png', file });
+     * const stop = task.onProgress((p) => setPercent(Math.round(p.fraction * 100)));
+     * cancelButton.onclick = () => task.cancel();
+     * const { object } = await task.result;
+     */
+    startUpload(options) {
+        return runUploadTask((task) => this.runUpload(options, task));
+    }
+    async runUpload(options, task) {
+        task.checkCancelled();
         const overwrite = options.overwrite ?? false;
         // A Blob (browser File included) knows its own type; the React Native
         // URI form carries it alongside. Falling back to octet-stream keeps a
@@ -97,8 +139,10 @@ export class KoolbaseStorage {
         const contentType = isBlob
             ? options.file.type || 'application/octet-stream'
             : options.file.type;
+        if (isBlob)
+            task.setTotal(options.file.size);
         // ─── Step 1: Get presigned upload URL ───
-        const urlRes = await koolbaseFetch(`${this.config.baseUrl}/v1/sdk/storage/upload-url`, {
+        const urlRes = await sessionFetch(`${this.config.baseUrl}/v1/sdk/storage/upload-url`, {
             method: 'POST',
             headers: {
                 ...(await this.buildHeaders()),
@@ -114,7 +158,8 @@ export class KoolbaseStorage {
         if (!urlRes.ok) {
             throw await this.error(urlRes, 'Failed to get upload URL');
         }
-        const { upload_url } = (await urlRes.json());
+        const { upload_url, upload_id } = (await urlRes.json());
+        task.checkCancelled();
         // ─── Step 2: Upload directly to R2 ───
         // R2 presigned URLs expect raw binary, NOT multipart/form-data.
         //
@@ -124,19 +169,19 @@ export class KoolbaseStorage {
         // the two hosts differ here and nowhere else in this method.
         const fileBlob = isBlob
             ? options.file
-            : await (await koolbaseFetch(options.file.uri)).blob();
+            : await (await sessionFetch(options.file.uri)).blob();
         const fileSize = fileBlob.size;
-        const uploadRes = await koolbaseFetch(upload_url, {
-            method: 'PUT',
-            headers: { 'Content-Type': contentType },
-            body: fileBlob,
-        });
-        if (!uploadRes.ok) {
+        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
             // generic storage error rather than trying to decode a Koolbase body.
             throw new KoolbaseStorageError(`Upload to storage failed: ${uploadRes.status}`);
         }
-        const etag = uploadRes.headers.get('etag') ?? '';
+        const etag = uploadRes.etag;
+        // From here the server checks the bytes and puts them in place; the
+        // upload can no longer be cancelled.
+        task.verifying();
         // ─── Step 3: Confirm upload ───
         // Build the body conditionally so the `metadata` field is only sent
         // when the caller passed it — keeps the wire shape clean for callers
@@ -150,10 +195,14 @@ export class KoolbaseStorage {
             etag,
             overwrite,
         };
+        // The confirm names its upload, so it takes exactly these bytes.
+        if (upload_id) {
+            confirmBody.upload_id = upload_id;
+        }
         if (options.metadata !== undefined) {
             confirmBody.metadata = options.metadata;
         }
-        const confirmRes = await koolbaseFetch(`${this.config.baseUrl}/v1/sdk/storage/confirm`, {
+        const confirmRes = await sessionFetch(`${this.config.baseUrl}/v1/sdk/storage/confirm`, {
             method: 'POST',
             headers: {
                 ...(await this.buildHeaders()),
@@ -170,6 +219,40 @@ export class KoolbaseStorage {
         const downloadUrl = await this.getDownloadUrl(options.bucket, options.path);
         return { object, downloadUrl };
     }
+    /**
+     * 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
+     * page's `nextCursor` back as `cursor` for the next one; a page can hold
+     * fewer files than `limit` and still have a next.
+     *
+     * @example
+     * let cursor: string | undefined;
+     * do {
+     *   const page = await Koolbase.storage.listFiles({ bucket: 'posters', prefix: 'events/', cursor });
+     *   show(page.files);
+     *   cursor = page.nextCursor ?? undefined;
+     * } while (cursor);
+     */
+    async listFiles(options) {
+        const res = await sessionFetch(`${this.config.baseUrl}/v1/sdk/storage/files?${listFilesQuery(options)}`, { headers: await this.buildHeaders() });
+        if (!res.ok) {
+            throw await this.error(res, 'Failed to list files');
+        }
+        return filePageFromJson((await res.json()));
+    }
+    /**
+     * One file's details -- size, type, metadata, who uploaded it, and its
+     * permanent link while its bucket is public. Throws
+     * `KoolbaseStorageNotFoundError` for a file that is not there or that
+     * the bucket's view rule hides from the caller.
+     */
+    async getFileInfo(bucket, path) {
+        const res = await sessionFetch(`${this.config.baseUrl}/v1/sdk/storage/file?bucket=${encodeURIComponent(bucket)}&path=${encodeURIComponent(path)}`, { headers: await this.buildHeaders() });
+        if (!res.ok) {
+            throw await this.error(res, 'Failed to get the file');
+        }
+        return fileInfoFromJson((await res.json()));
+    }
     /**
      * Apply a partial metadata update to an existing object. Returns the
      * post-update {@link KoolbaseObject} with the merged metadata.
@@ -204,7 +287,7 @@ export class KoolbaseStorage {
      * // -> { category: 'landscape', tag: 'sunset' }
      */
     async updateMetadata(bucket, path, metadata) {
-        const res = await koolbaseFetch(`${this.config.baseUrl}/v1/sdk/storage/objects/metadata`, {
+        const res = await sessionFetch(`${this.config.baseUrl}/v1/sdk/storage/objects/metadata`, {
             method: 'PATCH',
             headers: {
                 ...(await this.buildHeaders()),
@@ -227,7 +310,7 @@ export class KoolbaseStorage {
         if (versionId) {
             url += `&version_id=${encodeURIComponent(versionId)}`;
         }
-        const res = await koolbaseFetch(url, { headers: await this.buildHeaders() });
+        const res = await sessionFetch(url, { headers: await this.buildHeaders() });
         if (!res.ok) {
             throw await this.error(res, 'Failed to get download URL');
         }
@@ -339,7 +422,7 @@ export class KoolbaseStorage {
         const url = forcePurge
             ? `${this.config.baseUrl}/v1/sdk/storage/object?force_purge=true`
             : `${this.config.baseUrl}/v1/sdk/storage/object`;
-        const res = await koolbaseFetch(url, {
+        const res = await sessionFetch(url, {
             method: 'DELETE',
             headers: {
                 ...(await this.buildHeaders()),
@@ -366,7 +449,7 @@ export class KoolbaseStorage {
     async listVersions(bucket, path) {
         const url = `${this.config.baseUrl}/v1/sdk/storage/object-versions` +
             `?bucket=${encodeURIComponent(bucket)}&path=${encodeURIComponent(path)}`;
-        const res = await koolbaseFetch(url, { headers: await this.buildHeaders() });
+        const res = await sessionFetch(url, { headers: await this.buildHeaders() });
         if (!res.ok) {
             throw await this.error(res, 'Failed to list versions');
         }
@@ -382,7 +465,7 @@ export class KoolbaseStorage {
     async getVersion(bucket, path, versionId) {
         const url = `${this.config.baseUrl}/v1/sdk/storage/object-versions/${encodeURIComponent(versionId)}` +
             `?bucket=${encodeURIComponent(bucket)}&path=${encodeURIComponent(path)}`;
-        const res = await koolbaseFetch(url, { headers: await this.buildHeaders() });
+        const res = await sessionFetch(url, { headers: await this.buildHeaders() });
         if (!res.ok) {
             throw await this.error(res, 'Failed to fetch version');
         }
@@ -401,7 +484,7 @@ export class KoolbaseStorage {
     async restoreVersion(bucket, path, versionId) {
         const url = `${this.config.baseUrl}/v1/sdk/storage/object-versions/${encodeURIComponent(versionId)}/restore` +
             `?bucket=${encodeURIComponent(bucket)}&path=${encodeURIComponent(path)}`;
-        const res = await koolbaseFetch(url, {
+        const res = await sessionFetch(url, {
             method: 'POST',
             headers: await this.buildHeaders(),
         });
@@ -419,7 +502,7 @@ export class KoolbaseStorage {
     async purgeVersion(bucket, path, versionId) {
         const url = `${this.config.baseUrl}/v1/sdk/storage/object-versions/${encodeURIComponent(versionId)}` +
             `?bucket=${encodeURIComponent(bucket)}&path=${encodeURIComponent(path)}`;
-        const res = await koolbaseFetch(url, {
+        const res = await sessionFetch(url, {
             method: 'DELETE',
             headers: await this.buildHeaders(),
         });

package/dist/esm/sync-engine.js

@@ -1,4 +1,4 @@
-import { koolbaseFetch } from './network.js';
+import { sessionFetch } from './network.js';
 import { readOfflineState, mutateOfflineState, migrateLegacyQueue, flushLockName, } from './offline-state.js';
 import { KoolbaseUnauthenticatedError } from './errors.js';
 import { getPlatform } from './platform.js';
@@ -256,7 +256,7 @@ export class SyncEngine {
             : `${this.config.baseUrl}/v1/sdk/db/records/${write.recordId}`;
         let res;
         if (write.operation === 'insert') {
-            res = await koolbaseFetch(url, {
+            res = await sessionFetch(url, {
                 method: 'POST',
                 headers,
                 // The write's own id: generated at enqueue, identical on every retry.
@@ -270,7 +270,7 @@ export class SyncEngine {
             });
         }
         else if (write.operation === 'update') {
-            res = await koolbaseFetch(url, {
+            res = await sessionFetch(url, {
                 method: 'PATCH',
                 headers,
                 // The revision the change was composed against. The server applies it
@@ -289,7 +289,7 @@ export class SyncEngine {
             const q = write.baseRevision !== undefined
                 ? `?expected_revision=${write.baseRevision}`
                 : '';
-            res = await koolbaseFetch(`${url}${q}`, { method: 'DELETE', headers });
+            res = await sessionFetch(`${url}${q}`, { method: 'DELETE', headers });
         }
         if (res.status === 401)
             throw new KoolbaseUnauthenticatedError('unauthorized');

package/dist/esm/types.d.ts

@@ -180,6 +180,13 @@ export declare enum RestoreResult {
  * broken listener cannot break propagation to others.
  */
 export type AuthStateListener = (user: KoolbaseUser | null) => void;
+/**
+ * Why the last session ended (#104): the person signed out, or the session
+ * ended on its own -- revoked, expired past renewal, signed out elsewhere.
+ * An app tells them apart to say "You were signed out" only when they did
+ * not ask to be.
+ */
+export type SignOutReason = 'signed_out' | 'session_ended';
 /**
  * Drop-in replacement for the global `fetch` function. Inject via
  * KoolbaseConfig.fetch for testing (mock fetch), proxying, or
@@ -362,7 +369,18 @@ export interface UploadOptions {
      * for post-upload merge changes.
      */
     metadata?: Record<string, string>;
-    onProgress?: (percent: number) => void;
+    /**
+     * Called as the upload goes: `percent` is 0 to 100 of the bytes sent;
+     * `progress` says where the upload is (uploading, verifying, completed,
+     * ...). For a cancellable upload use `KoolbaseStorage.startUpload`.
+     */
+    onProgress?: (percent: number, progress: import('./storage-transfer.js').KoolbaseUploadProgress) => void;
+    /**
+     * Aborting this signal cancels the upload, if the server has not begun
+     * checking it yet; the upload then rejects with
+     * `KoolbaseUploadCancelledError`.
+     */
+    signal?: AbortSignal;
 }
 /**
  * A stored object's server-side metadata. Field names are camelCase here

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@koolbase/core",
-  "version": "12.14.0",
+  "version": "12.16.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",