feat(storage): edge image transforms (Gap #8) — v5.4.0

KoolbaseImageTransform type + format/fit/gravity unions for direct
transforms via Cloudflare /cdn-cgi/image/. Named presets via
publicUrlWithPreset resolving server-managed option sets at
cdn.koolbase.com/p/{project_id}/{preset_name}/...

- KoolbaseStorage.publicUrl({..., transform}) — optional opts
- KoolbaseStorage.publicUrlWithPreset({...})
- KoolbaseStorage.publicUrlForObjectWithPreset(obj, bucket, name)
- README: new Image transforms section
- CHANGELOG: 5.4.0 entry

Additive, backward-compatible. Existing publicUrl calls without
transform unchanged.

Author: kennedyowusu

CHANGELOG.md

@@ -7,6 +7,44 @@ adheres to [Semantic Versioning][semver].
 [kac]: https://keepachangelog.com/en/1.1.0/
 [semver]: https://semver.org/
 
+# 5.4.0
+
+### Added — storage
+
+- Edge image transforms (Gap #8). Two complementary forms:
+  - `KoolbaseStorage.publicUrl({ ..., transform })` accepts an
+    optional `KoolbaseImageTransform` object — width, height,
+    format, quality, fit, dpr, gravity. The resulting URL hits
+    Cloudflare's image pipeline at
+    `cdn.koolbase.com/cdn-cgi/image/<opts>/...` and serves a
+    resized, re-encoded copy of the source.
+  - `KoolbaseStorage.publicUrlWithPreset({ projectId, presetName,
+    bucket, path })` resolves a named preset stored server-side
+    (managed via the dashboard or REST API) at
+    `cdn.koolbase.com/p/{project_id}/{preset_name}/{bucket}/{path}`.
+    Edit the preset once on the server and every URL using it
+    updates as the edge cache rolls over.
+  - `KoolbaseStorage.publicUrlForObjectWithPreset(obj, bucket,
+    presetName)` — instance-style variant when you already have a
+    `KoolbaseObject` in hand.
+- New typed exports: `KoolbaseImageTransform`, `KoolbaseImageFormat`
+  (`'auto' | 'webp' | 'avif' | 'jpeg' | 'png'`), `KoolbaseImageFit`
+  (`'scale-down' | 'contain' | 'cover' | 'crop' | 'pad'`),
+  `KoolbaseImageGravity` (10 anchor positions). Out-of-range numeric
+  values clamp silently to Cloudflare's valid ranges (width/height
+  1–2000, quality 1–100, dpr 1–3).
+
+### Notes
+
+Cloudflare bills unique transformations per calendar month; every
+Koolbase account includes 5,000 free. Transformed responses are
+edge-cached for 4 hours.
+
+### Compatibility
+
+No breaking changes. All new APIs are additive; existing `publicUrl`
+calls without `transform` produce the exact same URL they did in 5.3.0.
+
 # 5.3.0
 
 ### Added — storage

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.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",

src/storage.ts

@@ -308,6 +308,49 @@ export class KoolbaseStorage {
     });
   }
 
+  /**
+   * 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 {
+    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: KoolbaseObject,
+    bucket: string,
+    presetName: string,
+  ): string | null {
+    if (obj.r2Bucket !== 'koolbase-storage-public') return null;
+    return KoolbaseStorage.publicUrlWithPreset({
+      projectId: obj.projectId,
+      presetName,
+      bucket,
+      path: obj.path,
+    });
+  }
+
   /**
    * Delete a file from a bucket.
    */