@techfinityedge/koolbase-react-native 5.4.0 → 5.5.0

package/README.md

@@ -485,6 +485,64 @@ so nothing leaks.
 
 ---
 
+### Object versioning
+
+For buckets with versioning enabled, every overwrite preserves the prior
+content as a history version, and deletes are soft (recoverable until
+force-purged). Enable versioning on a bucket from the dashboard.
+
+```typescript
+// List all versions of a path, newest first
+const versions = await Koolbase.storage.listVersions('documents', 'contract.pdf');
+
+for (const v of versions) {
+  console.log(`${v.versionId}: size=${v.size} isCurrent=${v.isCurrent}`);
+}
+
+// Download a specific historical version
+const url = await Koolbase.storage.getDownloadUrl(
+  'documents',
+  'contract.pdf',
+  '019e98ed-eed6-7e71-...',
+);
+
+// Bring a history version back as current
+// (the existing current is snapshotted to history first)
+const restored = await Koolbase.storage.restoreVersion(
+  'documents',
+  'contract.pdf',
+  '019e98ed-eed6-7e71-...',
+);
+
+// Hard-remove a single history version (row + R2 bytes)
+await Koolbase.storage.purgeVersion(
+  'documents',
+  'contract.pdf',
+  'old-version-id',
+);
+
+// Wipe the entire timeline for a path - every version, every R2 key
+await Koolbase.storage.delete('documents', 'contract.pdf', true);
+```
+
+A few behaviors worth knowing:
+
+- **Overwrite snapshots automatically.** Upload to a path that already
+  exists in a versioned bucket and the prior bytes are preserved as
+  history; the upload becomes the new current.
+- **Delete is soft by default.** On a versioned bucket, `delete`
+  snapshots the current content and records a delete marker. The
+  content is still recoverable via `restoreVersion` until force-purged.
+- **Restore is itself a versioned event.** The previously-current row
+  gets snapshotted before the target's bytes overwrite canonical. The
+  restored row gets a fresh `versionId`; the target stays in history at
+  its original id - so you can always undo a restore.
+- **Delete markers can be listed but not downloaded.** A marker has
+  `size === 0`, `isDeleteMarker === true`, and no bytes. Calling
+  `getDownloadUrl` with a marker's `versionId` throws.
+
+---
+
 ## Realtime
 
 Subscribe to live changes on a collection. Uses the signed-in user's session, so
@@ -771,7 +829,7 @@ try {
 
 - Authentication: email + password, Apple Sign-In, Google Sign-In, phone + OTP
 - Database with offline-first cache, realtime subscriptions, and populate
-- Storage with presigned uploads and downloads, safe-by-default conflict handling
+- Storage with presigned uploads and downloads, safe-by-default conflict handling, image transforms, object versioning (history + restore + soft-delete)
 - Realtime subscriptions over WebSocket
 - Authenticated functions (`ctx.auth` exposes the caller automatically)
 - Feature flags and remote config

package/dist/storage.d.ts

@@ -1,4 +1,4 @@
-import { KoolbaseConfig, UploadOptions, UploadResult, KoolbaseObject, KoolbaseImageTransform } from './types';
+import { KoolbaseConfig, UploadOptions, UploadResult, KoolbaseObject, KoolbaseObjectVersion, KoolbaseImageTransform } from './types';
 /**
  * Koolbase storage client — uploads, downloads, and deletes via presigned
  * Cloudflare R2 URLs.
@@ -72,7 +72,7 @@ export declare class KoolbaseStorage {
     /**
      * Get a signed download URL for a file.
      */
-    getDownloadUrl(bucket: string, path: string): Promise<string>;
+    getDownloadUrl(bucket: string, path: string, versionId?: string): Promise<string>;
     /**
      * Build the stable public CDN URL for a file in a public bucket.
      *
@@ -145,5 +145,40 @@ export declare class KoolbaseStorage {
     /**
      * Delete a file from a bucket.
      */
-    delete(bucket: string, path: string): Promise<void>;
+    delete(bucket: string, path: string, forcePurge?: boolean): Promise<void>;
+    /**
+     * List all versions of a file path, newest-first. Returns a flat list
+     * mixing the current row (with `isCurrent: true`) and all history
+     * rows. Delete markers are included so callers can render the full
+     * timeline; filter client-side to hide them if the UI only wants
+     * restorable versions.
+     *
+     * Returns an empty array (not an error) when the path has no history
+     * and no current row.
+     */
+    listVersions(bucket: string, path: string): Promise<KoolbaseObjectVersion[]>;
+    /**
+     * Fetch metadata for a single version by id. Works against both the
+     * current row and any history row — the response's `isCurrent` tells
+     * you which.
+     */
+    getVersion(bucket: string, path: string, versionId: string): Promise<KoolbaseObjectVersion>;
+    /**
+     * Bring a history version back as the current version. The
+     * previously-current row (if any) is snapshotted into history first,
+     * so this operation is itself a versioned event you can undo. The
+     * restored row gets a freshly-minted version_id; the target stays in
+     * history at its original version_id.
+     *
+     * Throws if the bucket has versioning off, if the target is the
+     * already-current version, or if the target is a delete marker.
+     */
+    restoreVersion(bucket: string, path: string, versionId: string): Promise<KoolbaseObject>;
+    /**
+     * Hard-remove a single history version — both the metadata row and
+     * the .versions/ R2 bytes (or just the row, for delete markers).
+     * Refuses to operate on the current version; use {@link delete} with
+     * `forcePurge: true` to wipe everything for a path.
+     */
+    purgeVersion(bucket: string, path: string, versionId: string): Promise<void>;
 }

package/dist/storage.js

@@ -195,9 +195,12 @@ class KoolbaseStorage {
     /**
      * Get a signed download URL for a file.
      */
-    async getDownloadUrl(bucket, path) {
-        const url = `${this.config.baseUrl}/v1/sdk/storage/download-url` +
+    async getDownloadUrl(bucket, path, versionId) {
+        let url = `${this.config.baseUrl}/v1/sdk/storage/download-url` +
             `?bucket=${encodeURIComponent(bucket)}&path=${encodeURIComponent(path)}`;
+        if (versionId) {
+            url += `&version_id=${encodeURIComponent(versionId)}`;
+        }
         const res = await fetch(url, { headers: await this.buildHeaders() });
         if (!res.ok) {
             throw await (0, storage_errors_1.koolbaseStorageErrorFromResponse)(res, 'Failed to get download URL');
@@ -289,8 +292,11 @@ class KoolbaseStorage {
     /**
      * Delete a file from a bucket.
      */
-    async delete(bucket, path) {
-        const res = await fetch(`${this.config.baseUrl}/v1/sdk/storage/object`, {
+    async delete(bucket, path, forcePurge) {
+        const url = forcePurge
+            ? `${this.config.baseUrl}/v1/sdk/storage/object?force_purge=true`
+            : `${this.config.baseUrl}/v1/sdk/storage/object`;
+        const res = await fetch(url, {
             method: 'DELETE',
             headers: {
                 ...(await this.buildHeaders()),
@@ -304,6 +310,82 @@ class KoolbaseStorage {
             throw await (0, storage_errors_1.koolbaseStorageErrorFromResponse)(res, 'Failed to delete file');
         }
     }
+    /**
+     * List all versions of a file path, newest-first. Returns a flat list
+     * mixing the current row (with `isCurrent: true`) and all history
+     * rows. Delete markers are included so callers can render the full
+     * timeline; filter client-side to hide them if the UI only wants
+     * restorable versions.
+     *
+     * Returns an empty array (not an error) when the path has no history
+     * and no current row.
+     */
+    async listVersions(bucket, path) {
+        const url = `${this.config.baseUrl}/v1/sdk/storage/object-versions` +
+            `?bucket=${encodeURIComponent(bucket)}&path=${encodeURIComponent(path)}`;
+        const res = await fetch(url, { headers: await this.buildHeaders() });
+        if (!res.ok) {
+            throw await (0, storage_errors_1.koolbaseStorageErrorFromResponse)(res, 'Failed to list versions');
+        }
+        const data = (await res.json());
+        const list = Array.isArray(data.versions) ? data.versions : [];
+        return list.map((v) => fromVersionJson(v));
+    }
+    /**
+     * Fetch metadata for a single version by id. Works against both the
+     * current row and any history row — the response's `isCurrent` tells
+     * you which.
+     */
+    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 fetch(url, { headers: await this.buildHeaders() });
+        if (!res.ok) {
+            throw await (0, storage_errors_1.koolbaseStorageErrorFromResponse)(res, 'Failed to fetch version');
+        }
+        return fromVersionJson((await res.json()));
+    }
+    /**
+     * Bring a history version back as the current version. The
+     * previously-current row (if any) is snapshotted into history first,
+     * so this operation is itself a versioned event you can undo. The
+     * restored row gets a freshly-minted version_id; the target stays in
+     * history at its original version_id.
+     *
+     * Throws if the bucket has versioning off, if the target is the
+     * already-current version, or if the target is a delete marker.
+     */
+    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 fetch(url, {
+            method: 'POST',
+            headers: await this.buildHeaders(),
+        });
+        if (!res.ok) {
+            throw await (0, storage_errors_1.koolbaseStorageErrorFromResponse)(res, 'Failed to restore version');
+        }
+        return mapObjectFromServer(await res.json());
+    }
+    /**
+     * Hard-remove a single history version — both the metadata row and
+     * the .versions/ R2 bytes (or just the row, for delete markers).
+     * Refuses to operate on the current version; use {@link delete} with
+     * `forcePurge: true` to wipe everything for a path.
+     */
+    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 fetch(url, {
+            method: 'DELETE',
+            headers: await this.buildHeaders(),
+        });
+        if (res.status === 204)
+            return;
+        if (!res.ok) {
+            throw await (0, storage_errors_1.koolbaseStorageErrorFromResponse)(res, 'Failed to purge version');
+        }
+    }
 }
 exports.KoolbaseStorage = KoolbaseStorage;
 /**
@@ -327,3 +409,30 @@ function mapObjectFromServer(raw) {
         updatedAt: raw.updated_at,
     };
 }
+/**
+ * Maps the snake_case server JSON of a version row to the camelCase
+ * {@link KoolbaseObjectVersion}. Mirrors `fromObjectJson` shape.
+ */
+function fromVersionJson(j) {
+    const rawMeta = j.metadata;
+    const metadata = {};
+    if (rawMeta && typeof rawMeta === 'object') {
+        for (const [k, v] of Object.entries(rawMeta)) {
+            if (typeof v === 'string')
+                metadata[k] = v;
+        }
+    }
+    return {
+        versionId: j.version_id ?? null,
+        path: j.path,
+        size: Number(j.size ?? 0),
+        contentType: j.content_type ?? null,
+        etag: j.etag ?? null,
+        metadata,
+        r2Bucket: j.r2_bucket ?? '',
+        userId: j.user_id ?? null,
+        isDeleteMarker: Boolean(j.is_delete_marker),
+        isCurrent: Boolean(j.is_current),
+        createdAt: j.created_at,
+    };
+}

package/dist/types.d.ts

@@ -212,6 +212,48 @@ export interface KoolbaseObject {
     /** ISO 8601 timestamp from the server. */
     updatedAt: string;
 }
+/**
+ * One entry in an object's version timeline. Covers both the current
+ * row (when {@link isCurrent} is true) and every history row, including
+ * soft-delete markers (when {@link isDeleteMarker} is true — size 0, no
+ * fetchable bytes). Returned from {@link KoolbaseStorage.listVersions}
+ * and {@link KoolbaseStorage.getVersion}; the underlying bytes are
+ * downloadable via {@link KoolbaseStorage.getDownloadUrl} with the
+ * `versionId` argument.
+ *
+ * `versionId` may be null only on legacy rows uploaded before versioning
+ * was enabled on the bucket — for those, {@link isCurrent} is true and
+ * the row carries no history identity yet (gets backfilled on the next
+ * overwrite).
+ */
+export interface KoolbaseObjectVersion {
+    versionId: string | null;
+    path: string;
+    size: number;
+    contentType: string | null;
+    etag: string | null;
+    metadata: Record<string, string>;
+    r2Bucket: string;
+    userId: string | null;
+    /**
+     * True for a tombstone row recording a soft-delete event. Size is 0
+     * and there are no R2 bytes — treat as "the path was deleted at this
+     * time" rather than fetchable content.
+     */
+    isDeleteMarker: boolean;
+    /**
+     * True for the row that currently lives in `storage_objects` (i.e.
+     * what a no-versionId download returns). False for everything in
+     * `storage_object_versions`.
+     */
+    isCurrent: boolean;
+    /**
+     * For the current row this is the time the current version became
+     * current (overwrite or upload time). For history rows it's the time
+     * the version was originally uploaded.
+     */
+    createdAt: string;
+}
 /**
  * Result of a successful `KoolbaseStorage.upload()` call.
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@techfinityedge/koolbase-react-native",
-  "version": "5.4.0",
+  "version": "5.5.0",
   "description": "React Native SDK for Koolbase — auth, database, storage, realtime, feature flags, and functions in one package.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",