@techfinityedge/koolbase-react-native 5.3.0 → 5.5.0

package/README.md

@@ -235,6 +235,56 @@ URLs follow the pattern `https://cdn.koolbase.com/{project_id}/{bucket}/{path}`
 
 ---
 
+### Image transforms
+
+Public bucket URLs can be transformed at the edge — resize, reformat,
+optimize — without any preprocessing. Two ways:
+
+**Direct transforms** — pass a `transform` option to `publicUrl`:
+
+```ts
+const url = KoolbaseStorage.publicUrl({
+  projectId: 'proj_abc',
+  bucket: 'avatars',
+  path: 'user-123.jpg',
+  transform: {
+    width: 200,
+    height: 200,
+    fit: 'cover',
+    format: 'auto',
+    quality: 85,
+  },
+});
+```
+
+**Named presets** — store an option set server-side (via the dashboard or
+REST API), reference it by name:
+
+```ts
+const url = KoolbaseStorage.publicUrlWithPreset({
+  projectId: 'proj_abc',
+  presetName: 'thumbnail',
+  bucket: 'avatars',
+  path: 'user-123.jpg',
+});
+
+// Or from a KoolbaseObject instance:
+const url = KoolbaseStorage.publicUrlForObjectWithPreset(object, 'avatars', 'thumbnail');
+```
+
+Available options: `width` and `height` (1–2000), `format`
+(`auto`/`webp`/`avif`/`jpeg`/`png`), `quality` (1–100), `fit`
+(`scale-down`/`contain`/`cover`/`crop`/`pad`), `dpr` (1–3), `gravity`
+(`auto`/`center`/`top`/`bottom`/`left`/`right`/`top-left`/`top-right`/
+`bottom-left`/`bottom-right`). Transformed responses are edge-cached for 4
+hours; Cloudflare includes 5,000 unique transformations/month free per
+account.
+
+See the [Image Transforms docs](https://docs.koolbase.com/storage/image-transforms)
+for the full reference.
+
+---
+
 ### Upsert
 
 Insert a record, or update the existing one matching a filter.
@@ -435,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
@@ -721,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 } 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.
      *
@@ -91,6 +91,13 @@ export declare class KoolbaseStorage {
         projectId: string;
         bucket: string;
         path: string;
+        /**
+         * Optional Cloudflare Image Transformations. Adds a `/cdn-cgi/image/`
+         * URL prefix; billed against the koolbase.com zone's free monthly
+         * allocation (5,000 unique transforms/month). Each unique combination
+         * of `path` + options is cached and billed only once per calendar month.
+         */
+        transform?: KoolbaseImageTransform;
     }): string;
     /**
      * Returns the stable CDN URL for an object when its bytes physically
@@ -106,9 +113,72 @@ export declare class KoolbaseStorage {
      * carries only the bucket ID, not its name. Typically the caller
      * already knows which bucket they queried.
      */
-    static publicUrlForObject(obj: KoolbaseObject, bucket: string): string | null;
+    static publicUrlForObject(obj: KoolbaseObject, bucket: string, options?: {
+        transform?: KoolbaseImageTransform;
+    }): string | null;
+    /**
+     * Builds a named-preset CDN URL. The preset is resolved at the Cloudflare
+     * edge by the koolbase-cdn-worker, which looks up
+     * `preset:{project_id}:{preset_name}` in Workers KV and applies the stored
+     * transformation options. Presets are managed in the dashboard under
+     * Storage → Presets.
+     *
+     * Unknown preset names yield a 404 at the edge — the URL itself always
+     * constructs successfully without a network round-trip.
+     *
+     * For safer construction from an Object you already have, use
+     * {@link KoolbaseStorage.publicUrlForObjectWithPreset} — it checks the
+     * stored `r2Bucket` value and returns `null` when the object isn't in the
+     * public R2 bucket.
+     */
+    static publicUrlWithPreset(args: {
+        projectId: string;
+        presetName: string;
+        bucket: string;
+        path: string;
+    }): string;
+    /**
+     * Returns the named-preset CDN URL for the given object, or `null` if the
+     * object isn't in the public R2 bucket.
+     */
+    static publicUrlForObjectWithPreset(obj: KoolbaseObject, bucket: string, presetName: string): string | null;
     /**
      * 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

@@ -2,6 +2,35 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.KoolbaseStorage = void 0;
 const storage_errors_1 = require("./storage-errors");
+// --- Cloudflare image-transform URL helpers -------------------------------
+// Module-private — callers use KoolbaseStorage.publicUrl / publicUrlForObject.
+function clampInt(v, min, max) {
+    return Math.max(min, Math.min(max, Math.floor(v)));
+}
+/**
+ * Serializes a transform spec to Cloudflare's comma-separated key=value
+ * options segment (e.g. `width=400,format=webp,quality=80`). Returns the
+ * empty string when no fields are set — callers can use that to skip the
+ * `/cdn-cgi/image/` URL prefix entirely.
+ */
+function serializeTransform(t) {
+    const parts = [];
+    if (t.width != null)
+        parts.push(`width=${clampInt(t.width, 1, 2000)}`);
+    if (t.height != null)
+        parts.push(`height=${clampInt(t.height, 1, 2000)}`);
+    if (t.format)
+        parts.push(`format=${t.format}`);
+    if (t.quality != null)
+        parts.push(`quality=${clampInt(t.quality, 1, 100)}`);
+    if (t.fit)
+        parts.push(`fit=${t.fit}`);
+    if (t.dpr != null)
+        parts.push(`dpr=${clampInt(t.dpr, 1, 3)}`);
+    if (t.gravity)
+        parts.push(`gravity=${t.gravity}`);
+    return parts.join(',');
+}
 /**
  * Koolbase storage client — uploads, downloads, and deletes via presigned
  * Cloudflare R2 URLs.
@@ -166,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');
@@ -194,7 +226,11 @@ class KoolbaseStorage {
         // Encode each path segment individually so slashes are preserved
         // while spaces, parens, hashes, and query characters are escaped.
         const encoded = args.path.split('/').map(encodeURIComponent).join('/');
-        return `https://cdn.koolbase.com/${args.projectId}/${args.bucket}/${encoded}`;
+        const opts = args.transform ? serializeTransform(args.transform) : '';
+        if (!opts) {
+            return `https://cdn.koolbase.com/${args.projectId}/${args.bucket}/${encoded}`;
+        }
+        return `https://cdn.koolbase.com/cdn-cgi/image/${opts}/${args.projectId}/${args.bucket}/${encoded}`;
     }
     /**
      * Returns the stable CDN URL for an object when its bytes physically
@@ -210,16 +246,57 @@ class KoolbaseStorage {
      * carries only the bucket ID, not its name. Typically the caller
      * already knows which bucket they queried.
      */
-    static publicUrlForObject(obj, bucket) {
+    static publicUrlForObject(obj, bucket, options) {
+        if (obj.r2Bucket !== 'koolbase-storage-public')
+            return null;
+        return KoolbaseStorage.publicUrl({
+            projectId: obj.projectId,
+            bucket,
+            path: obj.path,
+            transform: options?.transform,
+        });
+    }
+    /**
+     * Builds a named-preset CDN URL. The preset is resolved at the Cloudflare
+     * edge by the koolbase-cdn-worker, which looks up
+     * `preset:{project_id}:{preset_name}` in Workers KV and applies the stored
+     * transformation options. Presets are managed in the dashboard under
+     * Storage → Presets.
+     *
+     * Unknown preset names yield a 404 at the edge — the URL itself always
+     * constructs successfully without a network round-trip.
+     *
+     * For safer construction from an Object you already have, use
+     * {@link KoolbaseStorage.publicUrlForObjectWithPreset} — it checks the
+     * stored `r2Bucket` value and returns `null` when the object isn't in the
+     * public R2 bucket.
+     */
+    static publicUrlWithPreset(args) {
+        const encoded = args.path.split('/').map(encodeURIComponent).join('/');
+        return `https://cdn.koolbase.com/p/${args.projectId}/${args.presetName}/${args.bucket}/${encoded}`;
+    }
+    /**
+     * Returns the named-preset CDN URL for the given object, or `null` if the
+     * object isn't in the public R2 bucket.
+     */
+    static publicUrlForObjectWithPreset(obj, bucket, presetName) {
         if (obj.r2Bucket !== 'koolbase-storage-public')
             return null;
-        return KoolbaseStorage.publicUrl({ projectId: obj.projectId, bucket, path: obj.path });
+        return KoolbaseStorage.publicUrlWithPreset({
+            projectId: obj.projectId,
+            presetName,
+            bucket,
+            path: obj.path,
+        });
     }
     /**
      * 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()),
@@ -233,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;
 /**
@@ -256,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.
  */
@@ -345,3 +387,37 @@ export interface BatchResult {
     /** True for a successful delete. */
     deleted?: boolean;
 }
+export type KoolbaseImageFormat = 'auto' | 'webp' | 'avif' | 'jpeg' | 'png';
+export type KoolbaseImageFit = 'scale-down' | 'contain' | 'cover' | 'crop' | 'pad';
+export type KoolbaseImageGravity = 'auto' | 'center' | 'top' | 'bottom' | 'left' | 'right' | 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+/**
+ * Image-transformation options for `KoolbaseStorage.publicUrl` and
+ * `KoolbaseStorage.publicUrlForObject`. Each field maps to one Cloudflare
+ * Image Transformations parameter; unset fields are omitted.
+ *
+ * All numeric inputs are clamped silently to Cloudflare-supported ranges
+ * (width/height 1-2000, quality 1-100, dpr 1-3) so a stray `width: 99999`
+ * can't trigger error 9422 at the edge.
+ *
+ * @example
+ * const url = KoolbaseStorage.publicUrl({
+ *   projectId: pid, bucket: 'avatars', path: 'user.jpg',
+ *   transform: { width: 400, height: 400, format: 'webp', quality: 80, fit: 'cover' },
+ * });
+ */
+export interface KoolbaseImageTransform {
+    /** Output width in pixels. Clamped to 1-2000. */
+    width?: number;
+    /** Output height in pixels. Clamped to 1-2000. */
+    height?: number;
+    /** Output format. `auto` negotiates based on the request's `Accept` header. */
+    format?: KoolbaseImageFormat;
+    /** Quality 1-100. Clamped. Has no effect on lossless formats (`png`). */
+    quality?: number;
+    /** Resize mode when both width and height are specified. */
+    fit?: KoolbaseImageFit;
+    /** Device pixel ratio multiplier. Clamped to 1-3. */
+    dpr?: number;
+    /** Crop anchor. Use with `fit: 'cover'` or `fit: 'crop'`. */
+    gravity?: KoolbaseImageGravity;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@techfinityedge/koolbase-react-native",
-  "version": "5.3.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",