@techfinityedge/koolbase-react-native 5.2.0 → 5.4.0

package/README.md

@@ -73,6 +73,8 @@ const unsubscribe = Koolbase.auth.onAuthStateChange((user) => {
 });
 ```
 
+---
+
 ### OAuth — Apple
 
 Apple Sign-In uses the native authentication flow via `@invertase/react-native-apple-authentication` as a peer dependency:
@@ -100,6 +102,8 @@ const session = await Koolbase.auth.signInWithApple({
 
 Configure Apple Sign-In for your environment with your iOS app's Bundle ID. Full setup guide at [docs.koolbase.com/auth/oauth](https://docs.koolbase.com/auth/oauth).
 
+---
+
 ### OAuth — Google
 
 Google Sign-In uses the native authentication flow via `@react-native-google-signin/google-signin` as a peer dependency:
@@ -121,6 +125,8 @@ const session = await Koolbase.auth.signInWithGoogle({
 
 Configure Google Sign-In for your environment with the OAuth client IDs from Google Cloud Console (typically one each for iOS, Android, and web). Full setup guide at [docs.koolbase.com/auth/oauth](https://docs.koolbase.com/auth/oauth).
 
+---
+
 ### Phone + OTP
 
 ```typescript
@@ -173,6 +179,8 @@ await Koolbase.db.update('record-id', { title: 'Updated' });
 await Koolbase.db.delete('record-id');
 ```
 
+---
+
 ### Handling unique-constraint conflicts
 
 A write that would violate a unique constraint throws `KoolbaseConflictError`:
@@ -187,6 +195,96 @@ try {
 }
 ```
 
+---
+
+### Public bucket URLs
+
+For files in public buckets, you can construct the stable CDN URL directly — no
+network call, no expiry, embeddable anywhere a browser fetches a URL.
+
+```typescript
+import { KoolbaseStorage } from '@techfinityedge/koolbase-react-native';
+
+// From a KoolbaseObject you already have (e.g. from upload() or another read)
+const { object } = await Koolbase.storage.upload({
+  bucket: 'avatars',
+  path: `user-${userId}.jpg`,
+  file: { uri: imageUri, name: 'avatar.jpg', type: 'image/jpeg' },
+});
+
+const url = KoolbaseStorage.publicUrlForObject(object, 'avatars');
+// url is null for private-bucket objects; the CDN URL for public-bucket ones.
+
+if (url) {
+  // Safe to use — file lives in the public R2 bucket
+  return <Image source={{ uri: url }} />;
+}
+
+// For build-time URL construction (no Object on hand)
+const url = KoolbaseStorage.publicUrl({
+  projectId: 'proj_abc',
+  bucket: 'avatars',
+  path: 'user-123.jpg',
+});
+// Always returns the URL pattern; caller is responsible for knowing
+// the file lives in a public bucket. For files in private buckets,
+// the resulting URL will 404.
+```
+
+URLs follow the pattern `https://cdn.koolbase.com/{project_id}/{bucket}/{path}` — long-lived, edge-cached, no authentication. For files in private buckets, use `getDownloadUrl` instead, which returns a 1-hour presigned URL.
+
+---
+
+### 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.
@@ -230,6 +328,8 @@ if (isFromCache) console.log('Served from local cache');
 await Koolbase.db.syncPendingWrites();
 ```
 
+---
+
 ### Atomic batch writes
 
 Run multiple writes in a single server-side transaction. All operations commit together or none are applied — any failure rolls back the entire batch.
@@ -309,6 +409,8 @@ const url = await Koolbase.storage.getDownloadUrl('avatars', `user-${userId}.jpg
 await Koolbase.storage.delete('avatars', `user-${userId}.jpg`);
 ```
 
+---
+
 ### Handling upload conflicts
 
 For user-supplied filenames, prompt the user before overwriting:
@@ -622,6 +724,8 @@ try {
 > the background, so their conflicts surface via the sync engine, not as a
 > thrown error.
 
+---
+
 ### Storage errors
 
 All storage failures extend `KoolbaseStorageError` (which extends `Error`):

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.
@@ -73,6 +73,75 @@ export declare class KoolbaseStorage {
      * Get a signed download URL for a file.
      */
     getDownloadUrl(bucket: string, path: string): Promise<string>;
+    /**
+     * Build the stable public CDN URL for a file in a public bucket.
+     *
+     * Returns the URL unconditionally — no check on whether the file
+     * exists or whether the bucket is actually public. Use when you
+     * know the file is in a public bucket and want the URL without a
+     * network round-trip (build-time URL generation, server-side
+     * rendering, batch image processing, etc.).
+     *
+     * For safer construction from an Object you already have, use
+     * {@link KoolbaseStorage.publicUrlForObject} — it checks the stored
+     * `r2Bucket` value and returns `null` when the object isn't in the
+     * public R2 bucket.
+     */
+    static publicUrl(args: {
+        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
+     * live in the public R2 bucket, `null` otherwise.
+     *
+     * Returns `null` for:
+     * - Files in private buckets (no public URL ever)
+     * - Legacy files in public buckets whose bytes still live in the
+     *   private R2 bucket from before Gap #2 (no permanent URL until
+     *   they're re-uploaded)
+     *
+     * The bucket name must be supplied because {@link KoolbaseObject}
+     * carries only the bucket ID, not its name. Typically the caller
+     * already knows which bucket they queried.
+     */
+    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.
@@ -176,6 +205,87 @@ class KoolbaseStorage {
         const data = (await res.json());
         return data.url;
     }
+    /**
+     * Build the stable public CDN URL for a file in a public bucket.
+     *
+     * Returns the URL unconditionally — no check on whether the file
+     * exists or whether the bucket is actually public. Use when you
+     * know the file is in a public bucket and want the URL without a
+     * network round-trip (build-time URL generation, server-side
+     * rendering, batch image processing, etc.).
+     *
+     * For safer construction from an Object you already have, use
+     * {@link KoolbaseStorage.publicUrlForObject} — it checks the stored
+     * `r2Bucket` value and returns `null` when the object isn't in the
+     * public R2 bucket.
+     */
+    static publicUrl(args) {
+        // 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('/');
+        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
+     * live in the public R2 bucket, `null` otherwise.
+     *
+     * Returns `null` for:
+     * - Files in private buckets (no public URL ever)
+     * - Legacy files in public buckets whose bytes still live in the
+     *   private R2 bucket from before Gap #2 (no permanent URL until
+     *   they're re-uploaded)
+     *
+     * The bucket name must be supplied because {@link KoolbaseObject}
+     * carries only the bucket ID, not its name. Typically the caller
+     * already knows which bucket they queried.
+     */
+    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.publicUrlWithPreset({
+            projectId: obj.projectId,
+            presetName,
+            bucket,
+            path: obj.path,
+        });
+    }
     /**
      * Delete a file from a bucket.
      */
@@ -212,6 +322,7 @@ function mapObjectFromServer(raw) {
         size: raw.size ?? 0,
         contentType: raw.content_type ?? null,
         metadata: raw.metadata ?? {},
+        r2Bucket: raw.r2_bucket ?? 'koolbase-storage',
         createdAt: raw.created_at,
         updatedAt: raw.updated_at,
     };

package/dist/types.d.ts

@@ -185,6 +185,16 @@ export interface KoolbaseObject {
     id: string;
     projectId: string;
     bucketId: string;
+    /**
+     * Name of the physical R2 bucket holding this object's bytes
+     * (Gap #2). `'koolbase-storage-public'` means the object has a
+     * stable CDN URL — construct it with
+     * `KoolbaseStorage.publicUrlForObject(obj, bucket)`. Anything else
+     * (typically `'koolbase-storage'`) means the object is in private
+     * storage and reads go through {@link KoolbaseStorage.getDownloadUrl},
+     * which returns a 1-hour presigned URL.
+     */
+    r2Bucket: string;
     userId: string | null;
     path: string;
     size: number;
@@ -335,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.2.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",
@@ -27,6 +27,8 @@
   },
   "devDependencies": {
     "@types/jszip": "^3.4.0",
+    "@types/node": "^25.9.1",
+    "react-native": "^0.85.3",
     "react-native-keychain": "^10.0.0",
     "typescript": "^5.0.0"
   },