@techfinityedge/koolbase-react-native 5.3.0 → 5.4.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.

package/dist/storage.d.ts

@@ -1,4 +1,4 @@
-import { KoolbaseConfig, UploadOptions, UploadResult, KoolbaseObject } from './types';
+import { KoolbaseConfig, UploadOptions, UploadResult, KoolbaseObject, KoolbaseImageTransform } from './types';
 /**
  * Koolbase storage client — uploads, downloads, and deletes via presigned
  * Cloudflare R2 URLs.
@@ -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,7 +113,35 @@ 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.
      */

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.
@@ -194,7 +223,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,10 +243,48 @@ 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.

package/dist/types.d.ts

@@ -345,3 +345,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.4.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",