@koolbase/core 12.8.0 → 12.9.0

package/dist/cjs/flags.d.ts

@@ -3,8 +3,21 @@ export declare class KoolbaseFlags {
     private config;
     private payload;
     private deviceId;
+    private lastArgs;
+    private inFlight;
     constructor(config: KoolbaseConfig, deviceId: string);
     koolbaseFetch(appVersion: string, platform: string): Promise<void>;
+    /**
+     * The project id learned from the bootstrap payload, or '' while the first
+     * bootstrap has not completed (storage's publicUrlFor reads it).
+     */
+    projectId(): string;
+    /**
+     * Fetch the bootstrap payload again with the last arguments -- a nudge from
+     * storage when identity is missing, so a startup failure heals within the
+     * session. One fetch at a time; never throws.
+     */
+    refresh(): Promise<void>;
     isEnabled(key: string): boolean;
     getString(key: string, fallback?: string): string;
     getNumber(key: string, fallback?: number): number;

package/dist/cjs/flags.js

@@ -5,10 +5,15 @@ const network_js_1 = require("./network.js");
 class KoolbaseFlags {
     constructor(config, deviceId) {
         this.payload = null;
+        // The last bootstrap's arguments, so a nudge can refresh with the same ones;
+        // and the fetch in flight, so nudges never stack.
+        this.lastArgs = null;
+        this.inFlight = null;
         this.config = config;
         this.deviceId = deviceId;
     }
     async koolbaseFetch(appVersion, platform) {
+        this.lastArgs = { appVersion, platform };
         try {
             const res = await (0, network_js_1.koolbaseFetch)(`${this.config.baseUrl}/v1/bootstrap?public_key=${this.config.publicKey}&device_id=${this.deviceId}&app_version=${appVersion}&platform=${platform}`);
             if (res.ok) {
@@ -17,6 +22,25 @@ class KoolbaseFlags {
         }
         catch (_) { }
     }
+    /**
+     * The project id learned from the bootstrap payload, or '' while the first
+     * bootstrap has not completed (storage's publicUrlFor reads it).
+     */
+    projectId() {
+        return this.payload?.project_id ?? '';
+    }
+    /**
+     * Fetch the bootstrap payload again with the last arguments -- a nudge from
+     * storage when identity is missing, so a startup failure heals within the
+     * session. One fetch at a time; never throws.
+     */
+    refresh() {
+        if (this.inFlight)
+            return this.inFlight;
+        const args = this.lastArgs ?? { appVersion: this.config.appVersion ?? '0.0.0', platform: 'unknown' };
+        this.inFlight = this.koolbaseFetch(args.appVersion, args.platform).finally(() => { this.inFlight = null; });
+        return this.inFlight;
+    }
     isEnabled(key) {
         const flag = this.payload?.flags[key];
         if (!flag || !flag.enabled || flag.kill_switch)

package/dist/cjs/storage-errors.d.ts

@@ -7,6 +7,22 @@ import { KoolbaseError } from './errors.js';
 export declare class KoolbaseStorageError extends KoolbaseError {
     constructor(message: string, code?: string);
 }
+/**
+ * Thrown by {@link KoolbaseStorage.publicUrlFor} when the SDK has not yet
+ * learned which project it belongs to. Project identity arrives with the
+ * bootstrap payload; it is unavailable until the first bootstrap completes
+ * (an app starting offline) or when the server predates identity metadata.
+ *
+ * A DIFFERENT state from a `null` public URL: null means the project is
+ * known but the object cannot have a public URL (private bucket). This one is
+ * transient: it heals on the next successful bootstrap, which calling
+ * publicUrlFor also nudges.
+ *
+ * Stable `code`: `project_identity_unavailable`.
+ */
+export declare class KoolbaseStorageProjectIdentityError extends KoolbaseStorageError {
+    constructor();
+}
 /**
  * Thrown when an upload is rejected because an object already exists at
  * the requested path — the server responds with 409 Conflict and code

package/dist/cjs/storage-errors.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.KoolbaseStorageMetadataInvalidError = exports.KoolbaseStorageMimeTypeError = exports.KoolbaseStorageFileTooLargeError = exports.KoolbaseStorageQuotaError = exports.KoolbaseCapBelowUsageError = exports.KoolbaseUploadExpiredError = exports.KoolbaseUploadURLFailedError = exports.KoolbaseStoragePermissionError = exports.KoolbaseStorageValidationError = exports.KoolbaseStorageNotFoundError = exports.KoolbaseStorageConflictError = exports.KoolbaseStorageError = void 0;
+exports.KoolbaseStorageMetadataInvalidError = exports.KoolbaseStorageMimeTypeError = exports.KoolbaseStorageFileTooLargeError = exports.KoolbaseStorageQuotaError = exports.KoolbaseCapBelowUsageError = exports.KoolbaseUploadExpiredError = exports.KoolbaseUploadURLFailedError = exports.KoolbaseStoragePermissionError = exports.KoolbaseStorageValidationError = exports.KoolbaseStorageNotFoundError = exports.KoolbaseStorageConflictError = exports.KoolbaseStorageProjectIdentityError = exports.KoolbaseStorageError = void 0;
 exports.koolbaseStorageError = koolbaseStorageError;
 exports.koolbaseStorageErrorFromResponse = koolbaseStorageErrorFromResponse;
 const errors_js_1 = require("./errors.js");
@@ -17,6 +17,27 @@ class KoolbaseStorageError extends errors_js_1.KoolbaseError {
     }
 }
 exports.KoolbaseStorageError = KoolbaseStorageError;
+/**
+ * Thrown by {@link KoolbaseStorage.publicUrlFor} when the SDK has not yet
+ * learned which project it belongs to. Project identity arrives with the
+ * bootstrap payload; it is unavailable until the first bootstrap completes
+ * (an app starting offline) or when the server predates identity metadata.
+ *
+ * A DIFFERENT state from a `null` public URL: null means the project is
+ * known but the object cannot have a public URL (private bucket). This one is
+ * transient: it heals on the next successful bootstrap, which calling
+ * publicUrlFor also nudges.
+ *
+ * Stable `code`: `project_identity_unavailable`.
+ */
+class KoolbaseStorageProjectIdentityError extends KoolbaseStorageError {
+    constructor() {
+        super('The SDK has not yet learned its project identity -- it arrives with the first successful bootstrap. Retry after connectivity is available.', 'project_identity_unavailable');
+        this.name = 'KoolbaseStorageProjectIdentityError';
+        Object.setPrototypeOf(this, KoolbaseStorageProjectIdentityError.prototype);
+    }
+}
+exports.KoolbaseStorageProjectIdentityError = KoolbaseStorageProjectIdentityError;
 /**
  * Thrown when an upload is rejected because an object already exists at
  * the requested path — the server responds with 409 Conflict and code

package/dist/cjs/storage.d.ts

@@ -19,7 +19,11 @@ export declare class KoolbaseStorage {
      * keeps believing it is signed in.
      */
     private onSessionExpired?;
-    constructor(config: KoolbaseConfig, getToken: () => Promise<string | null>, onSessionExpired?: () => Promise<void>);
+    /** The project id from the bootstrap payload, '' until it arrives. */
+    private projectIdProvider?;
+    /** A background bootstrap refresh, nudged when identity is missing. */
+    private nudgeBootstrap?;
+    constructor(config: KoolbaseConfig, getToken: () => Promise<string | null>, onSessionExpired?: () => Promise<void>, projectIdProvider?: () => string, nudgeBootstrap?: () => void);
     /**
      * Builds the error for a failed response and clears the session when the
      * credentials were refused, before the error reaches the caller.
@@ -87,6 +91,20 @@ export declare class KoolbaseStorage {
      * Get a signed download URL for a file.
      */
     getDownloadUrl(bucket: string, path: string, versionId?: string): Promise<string>;
+    /**
+     * The stable public CDN URL for a file in a public bucket, using the project
+     * identity the SDK learned at bootstrap -- the runtime form of
+     * {@link KoolbaseStorage.publicUrl}, needing no projectId (as Flutter's).
+     *
+     * Throws {@link KoolbaseStorageProjectIdentityError} while identity is
+     * unavailable, and nudges a background bootstrap refresh so a later call in
+     * the same session succeeds once connectivity returns.
+     */
+    publicUrlFor(args: {
+        bucket: string;
+        path: string;
+        transform?: KoolbaseImageTransform;
+    }): string;
     /**
      * Build the stable public CDN URL for a file in a public bucket.
      *

package/dist/cjs/storage.js

@@ -1,9 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.KoolbaseStorage = void 0;
+const storage_errors_js_1 = require("./storage-errors.js");
 const network_js_1 = require("./network.js");
 const errors_js_1 = require("./errors.js");
-const storage_errors_js_1 = require("./storage-errors.js");
+const storage_errors_js_2 = require("./storage-errors.js");
 // --- Cloudflare image-transform URL helpers -------------------------------
 // Module-private — callers use KoolbaseStorage.publicUrl / publicUrlForObject.
 function clampInt(v, min, max) {
@@ -42,17 +43,19 @@ function serializeTransform(t) {
  * `overwrite: true` is passed.
  */
 class KoolbaseStorage {
-    constructor(config, getToken, onSessionExpired) {
+    constructor(config, getToken, onSessionExpired, projectIdProvider, nudgeBootstrap) {
         this.config = config;
         this.getToken = getToken;
         this.onSessionExpired = onSessionExpired;
+        this.projectIdProvider = projectIdProvider;
+        this.nudgeBootstrap = nudgeBootstrap;
     }
     /**
      * Builds the error for a failed response and clears the session when the
      * credentials were refused, before the error reaches the caller.
      */
     async error(res, fallback) {
-        const err = await (0, storage_errors_js_1.koolbaseStorageErrorFromResponse)(res, fallback);
+        const err = await (0, storage_errors_js_2.koolbaseStorageErrorFromResponse)(res, fallback);
         if (err instanceof errors_js_1.KoolbaseUnauthenticatedError) {
             await this.onSessionExpired?.();
         }
@@ -134,7 +137,7 @@ class KoolbaseStorage {
         if (!uploadRes.ok) {
             // R2 PUT errors don't follow the Koolbase error shape — surface as a
             // generic storage error rather than trying to decode a Koolbase body.
-            throw new storage_errors_js_1.KoolbaseStorageError(`Upload to storage failed: ${uploadRes.status}`);
+            throw new storage_errors_js_2.KoolbaseStorageError(`Upload to storage failed: ${uploadRes.status}`);
         }
         const etag = uploadRes.headers.get('etag') ?? '';
         // ─── Step 3: Confirm upload ───
@@ -234,6 +237,23 @@ class KoolbaseStorage {
         const data = (await res.json());
         return data.url;
     }
+    /**
+     * The stable public CDN URL for a file in a public bucket, using the project
+     * identity the SDK learned at bootstrap -- the runtime form of
+     * {@link KoolbaseStorage.publicUrl}, needing no projectId (as Flutter's).
+     *
+     * Throws {@link KoolbaseStorageProjectIdentityError} while identity is
+     * unavailable, and nudges a background bootstrap refresh so a later call in
+     * the same session succeeds once connectivity returns.
+     */
+    publicUrlFor(args) {
+        const pid = this.projectIdProvider?.() ?? '';
+        if (pid === '') {
+            this.nudgeBootstrap?.();
+            throw new storage_errors_js_1.KoolbaseStorageProjectIdentityError();
+        }
+        return KoolbaseStorage.publicUrl({ projectId: pid, bucket: args.bucket, path: args.path, transform: args.transform });
+    }
     /**
      * Build the stable public CDN URL for a file in a public bucket.
      *

package/dist/cjs/types.d.ts

@@ -457,6 +457,9 @@ export interface RealtimeEvent {
 export type RealtimeCallback = (event: RealtimeEvent) => void;
 export interface BootstrapPayload {
     payload_version: string;
+    /** The project this public key belongs to: storage's publicUrlFor builds CDN
+     *  URLs with it. Absent from servers that predate identity metadata. */
+    project_id?: string;
     flags: Record<string, {
         enabled: boolean;
         rollout_percentage: number;

package/dist/esm/flags.d.ts

@@ -3,8 +3,21 @@ export declare class KoolbaseFlags {
     private config;
     private payload;
     private deviceId;
+    private lastArgs;
+    private inFlight;
     constructor(config: KoolbaseConfig, deviceId: string);
     koolbaseFetch(appVersion: string, platform: string): Promise<void>;
+    /**
+     * The project id learned from the bootstrap payload, or '' while the first
+     * bootstrap has not completed (storage's publicUrlFor reads it).
+     */
+    projectId(): string;
+    /**
+     * Fetch the bootstrap payload again with the last arguments -- a nudge from
+     * storage when identity is missing, so a startup failure heals within the
+     * session. One fetch at a time; never throws.
+     */
+    refresh(): Promise<void>;
     isEnabled(key: string): boolean;
     getString(key: string, fallback?: string): string;
     getNumber(key: string, fallback?: number): number;

package/dist/esm/flags.js

@@ -2,10 +2,15 @@ import { koolbaseFetch } from './network.js';
 export class KoolbaseFlags {
     constructor(config, deviceId) {
         this.payload = null;
+        // The last bootstrap's arguments, so a nudge can refresh with the same ones;
+        // and the fetch in flight, so nudges never stack.
+        this.lastArgs = null;
+        this.inFlight = null;
         this.config = config;
         this.deviceId = deviceId;
     }
     async koolbaseFetch(appVersion, platform) {
+        this.lastArgs = { appVersion, platform };
         try {
             const res = await koolbaseFetch(`${this.config.baseUrl}/v1/bootstrap?public_key=${this.config.publicKey}&device_id=${this.deviceId}&app_version=${appVersion}&platform=${platform}`);
             if (res.ok) {
@@ -14,6 +19,25 @@ export class KoolbaseFlags {
         }
         catch (_) { }
     }
+    /**
+     * The project id learned from the bootstrap payload, or '' while the first
+     * bootstrap has not completed (storage's publicUrlFor reads it).
+     */
+    projectId() {
+        return this.payload?.project_id ?? '';
+    }
+    /**
+     * Fetch the bootstrap payload again with the last arguments -- a nudge from
+     * storage when identity is missing, so a startup failure heals within the
+     * session. One fetch at a time; never throws.
+     */
+    refresh() {
+        if (this.inFlight)
+            return this.inFlight;
+        const args = this.lastArgs ?? { appVersion: this.config.appVersion ?? '0.0.0', platform: 'unknown' };
+        this.inFlight = this.koolbaseFetch(args.appVersion, args.platform).finally(() => { this.inFlight = null; });
+        return this.inFlight;
+    }
     isEnabled(key) {
         const flag = this.payload?.flags[key];
         if (!flag || !flag.enabled || flag.kill_switch)

package/dist/esm/storage-errors.d.ts

@@ -7,6 +7,22 @@ import { KoolbaseError } from './errors.js';
 export declare class KoolbaseStorageError extends KoolbaseError {
     constructor(message: string, code?: string);
 }
+/**
+ * Thrown by {@link KoolbaseStorage.publicUrlFor} when the SDK has not yet
+ * learned which project it belongs to. Project identity arrives with the
+ * bootstrap payload; it is unavailable until the first bootstrap completes
+ * (an app starting offline) or when the server predates identity metadata.
+ *
+ * A DIFFERENT state from a `null` public URL: null means the project is
+ * known but the object cannot have a public URL (private bucket). This one is
+ * transient: it heals on the next successful bootstrap, which calling
+ * publicUrlFor also nudges.
+ *
+ * Stable `code`: `project_identity_unavailable`.
+ */
+export declare class KoolbaseStorageProjectIdentityError extends KoolbaseStorageError {
+    constructor();
+}
 /**
  * Thrown when an upload is rejected because an object already exists at
  * the requested path — the server responds with 409 Conflict and code

package/dist/esm/storage-errors.js

@@ -11,6 +11,26 @@ export class KoolbaseStorageError extends KoolbaseError {
         Object.setPrototypeOf(this, KoolbaseStorageError.prototype);
     }
 }
+/**
+ * Thrown by {@link KoolbaseStorage.publicUrlFor} when the SDK has not yet
+ * learned which project it belongs to. Project identity arrives with the
+ * bootstrap payload; it is unavailable until the first bootstrap completes
+ * (an app starting offline) or when the server predates identity metadata.
+ *
+ * A DIFFERENT state from a `null` public URL: null means the project is
+ * known but the object cannot have a public URL (private bucket). This one is
+ * transient: it heals on the next successful bootstrap, which calling
+ * publicUrlFor also nudges.
+ *
+ * Stable `code`: `project_identity_unavailable`.
+ */
+export class KoolbaseStorageProjectIdentityError extends KoolbaseStorageError {
+    constructor() {
+        super('The SDK has not yet learned its project identity -- it arrives with the first successful bootstrap. Retry after connectivity is available.', 'project_identity_unavailable');
+        this.name = 'KoolbaseStorageProjectIdentityError';
+        Object.setPrototypeOf(this, KoolbaseStorageProjectIdentityError.prototype);
+    }
+}
 /**
  * Thrown when an upload is rejected because an object already exists at
  * the requested path — the server responds with 409 Conflict and code

package/dist/esm/storage.d.ts

@@ -19,7 +19,11 @@ export declare class KoolbaseStorage {
      * keeps believing it is signed in.
      */
     private onSessionExpired?;
-    constructor(config: KoolbaseConfig, getToken: () => Promise<string | null>, onSessionExpired?: () => Promise<void>);
+    /** The project id from the bootstrap payload, '' until it arrives. */
+    private projectIdProvider?;
+    /** A background bootstrap refresh, nudged when identity is missing. */
+    private nudgeBootstrap?;
+    constructor(config: KoolbaseConfig, getToken: () => Promise<string | null>, onSessionExpired?: () => Promise<void>, projectIdProvider?: () => string, nudgeBootstrap?: () => void);
     /**
      * Builds the error for a failed response and clears the session when the
      * credentials were refused, before the error reaches the caller.
@@ -87,6 +91,20 @@ export declare class KoolbaseStorage {
      * Get a signed download URL for a file.
      */
     getDownloadUrl(bucket: string, path: string, versionId?: string): Promise<string>;
+    /**
+     * The stable public CDN URL for a file in a public bucket, using the project
+     * identity the SDK learned at bootstrap -- the runtime form of
+     * {@link KoolbaseStorage.publicUrl}, needing no projectId (as Flutter's).
+     *
+     * Throws {@link KoolbaseStorageProjectIdentityError} while identity is
+     * unavailable, and nudges a background bootstrap refresh so a later call in
+     * the same session succeeds once connectivity returns.
+     */
+    publicUrlFor(args: {
+        bucket: string;
+        path: string;
+        transform?: KoolbaseImageTransform;
+    }): string;
     /**
      * Build the stable public CDN URL for a file in a public bucket.
      *

package/dist/esm/storage.js

@@ -1,3 +1,4 @@
+import { KoolbaseStorageProjectIdentityError } from './storage-errors.js';
 import { koolbaseFetch } from './network.js';
 import { KoolbaseUnauthenticatedError } from './errors.js';
 import { KoolbaseStorageError, koolbaseStorageErrorFromResponse, } from './storage-errors.js';
@@ -39,10 +40,12 @@ function serializeTransform(t) {
  * `overwrite: true` is passed.
  */
 export class KoolbaseStorage {
-    constructor(config, getToken, onSessionExpired) {
+    constructor(config, getToken, onSessionExpired, projectIdProvider, nudgeBootstrap) {
         this.config = config;
         this.getToken = getToken;
         this.onSessionExpired = onSessionExpired;
+        this.projectIdProvider = projectIdProvider;
+        this.nudgeBootstrap = nudgeBootstrap;
     }
     /**
      * Builds the error for a failed response and clears the session when the
@@ -231,6 +234,23 @@ export class KoolbaseStorage {
         const data = (await res.json());
         return data.url;
     }
+    /**
+     * The stable public CDN URL for a file in a public bucket, using the project
+     * identity the SDK learned at bootstrap -- the runtime form of
+     * {@link KoolbaseStorage.publicUrl}, needing no projectId (as Flutter's).
+     *
+     * Throws {@link KoolbaseStorageProjectIdentityError} while identity is
+     * unavailable, and nudges a background bootstrap refresh so a later call in
+     * the same session succeeds once connectivity returns.
+     */
+    publicUrlFor(args) {
+        const pid = this.projectIdProvider?.() ?? '';
+        if (pid === '') {
+            this.nudgeBootstrap?.();
+            throw new KoolbaseStorageProjectIdentityError();
+        }
+        return KoolbaseStorage.publicUrl({ projectId: pid, bucket: args.bucket, path: args.path, transform: args.transform });
+    }
     /**
      * Build the stable public CDN URL for a file in a public bucket.
      *

package/dist/esm/types.d.ts

@@ -457,6 +457,9 @@ export interface RealtimeEvent {
 export type RealtimeCallback = (event: RealtimeEvent) => void;
 export interface BootstrapPayload {
     payload_version: string;
+    /** The project this public key belongs to: storage's publicUrlFor builds CDN
+     *  URLs with it. Absent from servers that predate identity metadata. */
+    project_id?: string;
     flags: Record<string, {
         enabled: boolean;
         rollout_percentage: number;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@koolbase/core",
-  "version": "12.8.0",
-  "description": "Koolbase SDK core — shared behaviour behind @koolbase/react-native and @koolbase/js. Install one of those, not this.",
+  "version": "12.9.0",
+  "description": "Koolbase SDK core \u2014 shared behaviour behind @koolbase/react-native and @koolbase/js. Install one of those, not this.",
   "main": "./dist/cjs/index.js",
   "types": "./dist/esm/index.d.ts",
   "files": [