@techfinityedge/koolbase-react-native 5.2.0 → 5.3.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,46 @@ 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.
+
+---
+
 ### Upsert
 
 Insert a record, or update the existing one matching a filter.
@@ -230,6 +278,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 +359,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 +674,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

@@ -73,6 +73,40 @@ 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;
+    }): 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): string | null;
     /**
      * Delete a file from a bucket.
      */

package/dist/storage.js

@@ -176,6 +176,45 @@ 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('/');
+        return `https://cdn.koolbase.com/${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) {
+        if (obj.r2Bucket !== 'koolbase-storage-public')
+            return null;
+        return KoolbaseStorage.publicUrl({ projectId: obj.projectId, bucket, path: obj.path });
+    }
     /**
      * Delete a file from a bucket.
      */
@@ -212,6 +251,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;

package/package.json

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