@koolbase/core 12.15.0 → 12.17.0

package/dist/cjs/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,76 @@ 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>;
+    /**
+     * Move a file to `to`, in its bucket or into `toBucket` (S1b). Nothing is
+     * uploaded again. The bucket's rules decide: delete on the file, and
+     * upload at the destination, whose limits apply as to an upload. The
+     * destination must be free.
+     *
+     * Within one bucket the file keeps its kept versions. Refused with
+     * `KoolbaseStorageFileInUseError` while records point at the file: change
+     * them first, or {@link copy} it.
+     *
+     * @example
+     * await Koolbase.storage.move({ bucket: 'inbox', from: 'scan.png', toBucket: 'vault', to: '2026/scan.png' });
+     */
+    move(options: {
+        bucket: string;
+        from: string;
+        to: string;
+        toBucket?: string;
+    }): Promise<KoolbaseObject>;
+    /**
+     * Copy a file to `to`, in its bucket or into `toBucket` (S1b): a new file,
+     * the caller's, with the same bytes. The bucket's rules decide: view on
+     * the file, and upload at the destination.
+     */
+    copy(options: {
+        bucket: string;
+        from: string;
+        to: string;
+        toBucket?: string;
+    }): Promise<KoolbaseObject>;
+    private transfer;
     /**
      * Apply a partial metadata update to an existing object. Returns the
      * post-update {@link KoolbaseObject} with the merged metadata.

package/dist/cjs/storage.js

@@ -5,6 +5,8 @@ const storage_errors_js_1 = require("./storage-errors.js");
 const network_js_1 = require("./network.js");
 const errors_js_1 = require("./errors.js");
 const storage_errors_js_2 = require("./storage-errors.js");
+const storage_transfer_js_1 = require("./storage-transfer.js");
+const storage_files_js_1 = require("./storage-files.js");
 // --- Cloudflare image-transform URL helpers -------------------------------
 // Module-private — callers use KoolbaseStorage.publicUrl / publicUrlForObject.
 function clampInt(v, min, max) {
@@ -91,6 +93,46 @@ 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 (0, storage_transfer_js_1.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
@@ -100,6 +142,8 @@ 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 (0, network_js_1.sessionFetch)(`${this.config.baseUrl}/v1/sdk/storage/upload-url`, {
             method: 'POST',
@@ -117,7 +161,8 @@ 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.
         //
@@ -129,17 +174,17 @@ class KoolbaseStorage {
             ? options.file
             : await (await (0, network_js_1.sessionFetch)(options.file.uri)).blob();
         const fileSize = fileBlob.size;
-        const uploadRes = await (0, network_js_1.sessionFetch)(upload_url, {
-            method: 'PUT',
-            headers: { 'Content-Type': contentType },
-            body: fileBlob,
-        });
-        if (!uploadRes.ok) {
+        task.setTotal(fileSize);
+        const uploadRes = await (0, storage_transfer_js_1.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 storage_errors_js_2.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
@@ -153,6 +198,10 @@ 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;
         }
@@ -173,6 +222,78 @@ 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 (0, network_js_1.sessionFetch)(`${this.config.baseUrl}/v1/sdk/storage/files?${(0, storage_files_js_1.listFilesQuery)(options)}`, { headers: await this.buildHeaders() });
+        if (!res.ok) {
+            throw await this.error(res, 'Failed to list files');
+        }
+        return (0, storage_files_js_1.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 (0, network_js_1.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 (0, storage_files_js_1.fileInfoFromJson)((await res.json()));
+    }
+    /**
+     * Move a file to `to`, in its bucket or into `toBucket` (S1b). Nothing is
+     * uploaded again. The bucket's rules decide: delete on the file, and
+     * upload at the destination, whose limits apply as to an upload. The
+     * destination must be free.
+     *
+     * Within one bucket the file keeps its kept versions. Refused with
+     * `KoolbaseStorageFileInUseError` while records point at the file: change
+     * them first, or {@link copy} it.
+     *
+     * @example
+     * await Koolbase.storage.move({ bucket: 'inbox', from: 'scan.png', toBucket: 'vault', to: '2026/scan.png' });
+     */
+    async move(options) {
+        return this.transfer('move', options);
+    }
+    /**
+     * Copy a file to `to`, in its bucket or into `toBucket` (S1b): a new file,
+     * the caller's, with the same bytes. The bucket's rules decide: view on
+     * the file, and upload at the destination.
+     */
+    async copy(options) {
+        return this.transfer('copy', options);
+    }
+    async transfer(op, o) {
+        const body = { bucket: o.bucket, from: o.from, to: o.to };
+        if (o.toBucket && o.toBucket !== o.bucket)
+            body.to_bucket = o.toBucket;
+        const res = await (0, network_js_1.sessionFetch)(`${this.config.baseUrl}/v1/sdk/storage/${op}`, {
+            method: 'POST',
+            headers: { ...(await this.buildHeaders()), 'Content-Type': 'application/json' },
+            body: JSON.stringify(body),
+        });
+        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());
+    }
     /**
      * Apply a partial metadata update to an existing object. Returns the
      * post-update {@link KoolbaseObject} with the merged metadata.

package/dist/cjs/types.d.ts

@@ -369,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/dist/esm/index.d.ts

@@ -20,6 +20,9 @@ export { KoolbaseRealtime } from './realtime.js';
 export { KoolbaseConnectivity } from './connectivity.js';
 export type { ConnectivityState } from './connectivity.js';
 export { KoolbaseStorage } from './storage.js';
+export { KoolbaseUploadTask } from './storage-transfer.js';
+export type { KoolbaseUploadProgress, KoolbaseUploadState } from './storage-transfer.js';
+export type { KoolbaseFileInfo, KoolbaseFilePage, KoolbaseFileSort, ListFilesOptions } from './storage-files.js';
 export { KoolbaseAnalytics, disabledAnalytics } from './analytics.js';
 export { KoolbaseFiscal, KoolbaseFiscalError, decodeFiscalResponse, isFiscalized, isPending } from './fiscal.js';
 export type { FiscalIntentResult, FiscalStatus } from './fiscal.js';

package/dist/esm/index.js

@@ -22,6 +22,7 @@ export { KoolbaseFunctions } from './functions.js';
 export { KoolbaseRealtime } from './realtime.js';
 export { KoolbaseConnectivity } from './connectivity.js';
 export { KoolbaseStorage } from './storage.js';
+export { KoolbaseUploadTask } from './storage-transfer.js';
 export { KoolbaseAnalytics, disabledAnalytics } from './analytics.js';
 export { KoolbaseFiscal, KoolbaseFiscalError, decodeFiscalResponse, isFiscalized, isPending } from './fiscal.js';
 export { KoolbaseMessaging } from './messaging.js';

package/dist/esm/storage-errors.d.ts

@@ -187,6 +187,63 @@ export declare class KoolbaseStorageMetadataInvalidError extends KoolbaseStorage
     detail?: string;
     constructor(message?: string, detail?: string);
 }
+/**
+ * An upload that was cancelled -- by `KoolbaseUploadTask.cancel()` or the
+ * upload's `signal` -- before the server began checking it. Nothing was
+ * stored. Code: `upload_cancelled`.
+ */
+export declare class KoolbaseUploadCancelledError extends KoolbaseStorageError {
+    constructor(message?: string);
+}
+/**
+ * The confirm named an upload the server does not have: it expired, was
+ * confirmed already, or belongs to someone else. Upload the file again.
+ * Code: `upload_not_found`.
+ */
+export declare class KoolbaseUploadNotFoundError extends KoolbaseStorageError {
+    constructor(message?: string);
+}
+/**
+ * The bucket is busy with other changes (a large move, many uploads at
+ * once). Nothing was changed; retry shortly. Code: `bucket_busy`.
+ */
+export declare class KoolbaseStorageBusyError extends KoolbaseStorageError {
+    constructor(message?: string);
+}
+/**
+ * A listing's cursor was not one this listing issued -- made up, or from a
+ * listing with another sort or order. Start again from the first page.
+ * Code: `invalid_cursor`.
+ */
+export declare class KoolbaseStorageInvalidCursorError extends KoolbaseStorageError {
+    constructor(message?: string);
+}
+/**
+ * The bucket's rules allow this only to someone signed in, and nobody is.
+ * Not a session that ended: the SDK's session is left alone. Code:
+ * `sign_in_required`.
+ */
+export declare class KoolbaseStorageSignInRequiredError extends KoolbaseStorageError {
+    constructor(message?: string);
+}
+/**
+ * A move refused while records point at the file (S1b): `field` holds its
+ * path in `records` records. Change those first, or copy the file. Code:
+ * `file_in_use`.
+ */
+export declare class KoolbaseStorageFileInUseError extends KoolbaseStorageError {
+    field?: string;
+    records: number;
+    constructor(message?: string, field?: string, records?: number);
+}
+/**
+ * A move, within a bucket, to a name a deleted file's kept versions still
+ * use (S1b): the two histories would become one. Choose another name.
+ * Code: `name_has_history`.
+ */
+export declare class KoolbaseStorageNameHasHistoryError extends KoolbaseStorageError {
+    constructor(message?: string);
+}
 /**
  * Maps a non-2xx storage-layer response to a typed
  * {@link KoolbaseStorageError}, preferring the server's stable `code` and

package/dist/esm/storage-errors.js

@@ -234,6 +234,91 @@ export class KoolbaseStorageMetadataInvalidError extends KoolbaseStorageError {
         Object.setPrototypeOf(this, KoolbaseStorageMetadataInvalidError.prototype);
     }
 }
+/**
+ * An upload that was cancelled -- by `KoolbaseUploadTask.cancel()` or the
+ * upload's `signal` -- before the server began checking it. Nothing was
+ * stored. Code: `upload_cancelled`.
+ */
+export class KoolbaseUploadCancelledError extends KoolbaseStorageError {
+    constructor(message) {
+        super(message ?? 'The upload was cancelled', 'upload_cancelled');
+        this.name = 'KoolbaseUploadCancelledError';
+        Object.setPrototypeOf(this, KoolbaseUploadCancelledError.prototype);
+    }
+}
+/**
+ * The confirm named an upload the server does not have: it expired, was
+ * confirmed already, or belongs to someone else. Upload the file again.
+ * Code: `upload_not_found`.
+ */
+export class KoolbaseUploadNotFoundError extends KoolbaseStorageError {
+    constructor(message) {
+        super(message ?? 'This upload was not found -- please upload the file again', 'upload_not_found');
+        this.name = 'KoolbaseUploadNotFoundError';
+        Object.setPrototypeOf(this, KoolbaseUploadNotFoundError.prototype);
+    }
+}
+/**
+ * The bucket is busy with other changes (a large move, many uploads at
+ * once). Nothing was changed; retry shortly. Code: `bucket_busy`.
+ */
+export class KoolbaseStorageBusyError extends KoolbaseStorageError {
+    constructor(message) {
+        super(message ?? 'The bucket is busy -- try again shortly', 'bucket_busy');
+        this.name = 'KoolbaseStorageBusyError';
+        Object.setPrototypeOf(this, KoolbaseStorageBusyError.prototype);
+    }
+}
+/**
+ * A listing's cursor was not one this listing issued -- made up, or from a
+ * listing with another sort or order. Start again from the first page.
+ * Code: `invalid_cursor`.
+ */
+export class KoolbaseStorageInvalidCursorError extends KoolbaseStorageError {
+    constructor(message) {
+        super(message ?? 'The cursor is not valid for this listing', 'invalid_cursor');
+        this.name = 'KoolbaseStorageInvalidCursorError';
+        Object.setPrototypeOf(this, KoolbaseStorageInvalidCursorError.prototype);
+    }
+}
+/**
+ * The bucket's rules allow this only to someone signed in, and nobody is.
+ * Not a session that ended: the SDK's session is left alone. Code:
+ * `sign_in_required`.
+ */
+export class KoolbaseStorageSignInRequiredError extends KoolbaseStorageError {
+    constructor(message) {
+        super(message ?? 'Sign in to do this', 'sign_in_required');
+        this.name = 'KoolbaseStorageSignInRequiredError';
+        Object.setPrototypeOf(this, KoolbaseStorageSignInRequiredError.prototype);
+    }
+}
+/**
+ * A move refused while records point at the file (S1b): `field` holds its
+ * path in `records` records. Change those first, or copy the file. Code:
+ * `file_in_use`.
+ */
+export class KoolbaseStorageFileInUseError extends KoolbaseStorageError {
+    constructor(message, field, records = 0) {
+        super(message ?? 'Records still point at this file', 'file_in_use');
+        this.field = field;
+        this.records = records;
+        this.name = 'KoolbaseStorageFileInUseError';
+        Object.setPrototypeOf(this, KoolbaseStorageFileInUseError.prototype);
+    }
+}
+/**
+ * A move, within a bucket, to a name a deleted file's kept versions still
+ * use (S1b): the two histories would become one. Choose another name.
+ * Code: `name_has_history`.
+ */
+export class KoolbaseStorageNameHasHistoryError extends KoolbaseStorageError {
+    constructor(message) {
+        super(message ?? 'A deleted file by that name still has kept versions; choose another name', 'name_has_history');
+        this.name = 'KoolbaseStorageNameHasHistoryError';
+        Object.setPrototypeOf(this, KoolbaseStorageNameHasHistoryError.prototype);
+    }
+}
 /**
  * Maps a non-2xx storage-layer response to a typed
  * {@link KoolbaseStorageError}, preferring the server's stable `code` and
@@ -271,6 +356,22 @@ export function koolbaseStorageError(status, body, fallbackMessage = 'Storage re
             return new KoolbaseStorageMetadataInvalidError(message, body?.detail);
         case 'upload_url_failed':
             return new KoolbaseUploadURLFailedError(message);
+        case 'upload_not_found':
+            return new KoolbaseUploadNotFoundError(message);
+        case 'bucket_busy':
+            return new KoolbaseStorageBusyError(message);
+        case 'invalid_cursor':
+            return new KoolbaseStorageInvalidCursorError(message);
+        case 'sign_in_required':
+            return new KoolbaseStorageSignInRequiredError(message);
+        case 'not_allowed':
+            return new KoolbaseStoragePermissionError(message);
+        case 'file_in_use': {
+            const d = (body?.details ?? {});
+            return new KoolbaseStorageFileInUseError(message, d.field, Number(d.records ?? 0));
+        }
+        case 'name_has_history':
+            return new KoolbaseStorageNameHasHistoryError(message);
     }
     // ─── status fallback (pre-code servers or uncoded paths) ───
     switch (status) {

package/dist/esm/storage-files.d.ts

@@ -0,0 +1,53 @@
+/** What a listing is ordered by. */
+export type KoolbaseFileSort = 'path' | 'createdAt' | 'updatedAt' | 'size';
+export interface ListFilesOptions {
+    bucket: string;
+    /** Only files whose path starts with this, taken literally. */
+    prefix?: string;
+    /** Files per page: 50 unless set, at most 100. */
+    limit?: number;
+    /** A page's `nextCursor`, for the page after it. */
+    cursor?: string;
+    /** By path unless set. */
+    sort?: KoolbaseFileSort;
+    /** Z to A, newest first, largest first. */
+    descending?: boolean;
+}
+/** One file. */
+export interface KoolbaseFileInfo {
+    /** Its path in the bucket: what a record stores to point at it. */
+    path: string;
+    /** The last part of its path. */
+    name: string;
+    size: number;
+    contentType: string | null;
+    etag: string | null;
+    metadata: Record<string, string>;
+    versionId: string | null;
+    /** Who uploaded it: a project user's id; null when the project did. */
+    uploadedBy: string | null;
+    /** ISO 8601. */
+    createdAt: string;
+    /** ISO 8601. */
+    updatedAt: string;
+    /**
+     * Its permanent link, while its bucket is public; null otherwise -- ask
+     * for a download link instead.
+     */
+    publicUrl: string | null;
+}
+/** One page of a listing. */
+export interface KoolbaseFilePage {
+    files: KoolbaseFileInfo[];
+    /**
+     * Pass to the next call for the page after this one; null at the end. A
+     * page can hold fewer files than asked for -- the server passes over
+     * files you may not view -- and still have a next one.
+     */
+    nextCursor: string | null;
+    hasMore: boolean;
+}
+/** The query string for a listing. */
+export declare function listFilesQuery(o: ListFilesOptions): string;
+export declare function fileInfoFromJson(j: Record<string, unknown>): KoolbaseFileInfo;
+export declare function filePageFromJson(j: Record<string, unknown>): KoolbaseFilePage;

package/dist/esm/storage-files.js

@@ -0,0 +1,56 @@
+// A bucket's files, as an app sees them (S1).
+//
+// The server applies the bucket's view rule to every file: a listing holds
+// only files the signed-in person may view, and says nothing of the rest.
+const sortWire = {
+    path: 'path',
+    createdAt: 'created_at',
+    updatedAt: 'updated_at',
+    size: 'size',
+};
+/** The query string for a listing. */
+export function listFilesQuery(o) {
+    const q = new URLSearchParams();
+    q.set('bucket', o.bucket);
+    if (o.prefix)
+        q.set('prefix', o.prefix);
+    if (o.limit != null)
+        q.set('limit', String(o.limit));
+    if (o.cursor)
+        q.set('cursor', o.cursor);
+    q.set('sort', sortWire[o.sort ?? 'path'] ?? 'path');
+    q.set('order', o.descending ? 'desc' : 'asc');
+    return q.toString();
+}
+const str = (v) => (typeof v === 'string' && v !== '' ? v : null);
+export function fileInfoFromJson(j) {
+    const path = String(j.path ?? '');
+    const metadata = {};
+    if (j.metadata && typeof j.metadata === 'object') {
+        for (const [k, v] of Object.entries(j.metadata)) {
+            metadata[k] = typeof v === 'string' ? v : String(v);
+        }
+    }
+    return {
+        path,
+        name: path.split('/').pop() ?? path,
+        size: Number(j.size ?? 0),
+        contentType: str(j.content_type),
+        etag: str(j.etag),
+        metadata,
+        versionId: str(j.version_id),
+        uploadedBy: str(j.uploaded_by),
+        createdAt: String(j.created_at ?? ''),
+        updatedAt: String(j.updated_at ?? ''),
+        publicUrl: str(j.public_url),
+    };
+}
+export function filePageFromJson(j) {
+    const files = Array.isArray(j.files) ? j.files : [];
+    const nextCursor = str(j.next_cursor);
+    return {
+        files: files.map((f) => fileInfoFromJson(f)),
+        nextCursor,
+        hasMore: nextCursor !== null,
+    };
+}