@koolbase/js 10.0.0

package/CHANGELOG.md

@@ -0,0 +1,50 @@
+# Changelog
+
+All notable changes to `@koolbase/js` are documented in this file. The format
+is based on [Keep a Changelog][kac], and this project adheres to
+[Semantic Versioning][semver].
+
+[kac]: https://keepachangelog.com/en/1.1.0/
+[semver]: https://semver.org/
+
+## 10.0.0
+
+The first release. Numbered to match `@koolbase/react-native` and
+`@koolbase/core`, which share one version and one core: this package is that
+core composed for a browser, with sixty behavioural tests run against the
+browser adapter before it shipped.
+
+### What is here
+
+- **Auth** — email and password, phone + OTP, session persistence across
+  reloads, `restoreSession()`, `onAuthStateChange`, password reset, email
+  verification. Google and Apple sign-in through their web OAuth flows,
+  passing the ID token to the same `signInWithGoogle` / `signInWithApple`.
+- **Database** — insert, query, update, delete, upsert, bulk delete, atomic
+  batches, populate, and semantic / lexical / hybrid search.
+- **Offline** — cached reads, a durable write queue with baselines,
+  `pendingWrites()`, and conflicts you resolve four ways. Same semantics as
+  React Native, same tests.
+- **Storage** — presigned upload and download, safe-by-default paths, bucket
+  limits as typed errors, public CDN URLs with image transforms, versioning.
+- **Realtime** — one shared WebSocket, backoff on reconnect, events filtered
+  by the collection's read rule.
+- **Functions**, **feature flags**, **remote config**, **version
+  enforcement**, **analytics**.
+
+### What is not, by design
+
+- **Code push** — a native-bundle concept; the web ships on deploy.
+- **Push messaging** — FCM tokens come from a native module. Use Web Push
+  through a service worker and your backend.
+- **Native Google / Apple sign-in** — use the web OAuth flows.
+
+### Known limitations in this release
+
+- **Single tab.** Two tabs share one IndexedDB and one write queue. Inserts
+  are idempotent so the damage is bounded, but a conflict resolved in one tab
+  can be re-resolved in another. Multi-tab coordination is next.
+- **Session storage is not a keychain.** IndexedDB is readable by any script
+  on the page. Inject your own `KoolbaseAuthStorage` if your threat model
+  needs an httpOnly cookie or similar; the README says more.
+

package/README.md

@@ -0,0 +1,287 @@
+# @koolbase/js
+
+[![npm](https://img.shields.io/npm/v/@koolbase/js.svg)](https://www.npmjs.com/package/@koolbase/js)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+**From idea to app. And everything after.** Design your app, power it with a
+complete backend, and keep shipping after release.
+
+Koolbase for the browser: auth, database, storage, realtime, functions,
+feature flags, remote config, and an offline write queue with conflict
+resolution — one package, one `initialize()` call, TypeScript throughout.
+
+Same core as [`@koolbase/react-native`](https://www.npmjs.com/package/@koolbase/react-native).
+Same behaviour, proven by the same test suite on both hosts.
+
+---
+
+## Get started
+
+1. Create a free account at [app.koolbase.com](https://app.koolbase.com)
+2. Create a project and copy your public key from Environments
+3. Install:
+
+```bash
+npm install @koolbase/js
+```
+
+4. Initialize once at startup:
+
+```typescript
+import { Koolbase } from '@koolbase/js';
+
+await Koolbase.initialize({
+  publicKey: 'pk_live_xxxx',
+  baseUrl: 'https://api.koolbase.com',
+});
+```
+
+No native modules, no build step, nothing to configure. Works in any modern
+browser and in frameworks that render in one — React, Vue, Svelte, Next.js on
+the client side.
+
+> **Auth is automatic.** Database, storage and function calls authenticate as
+> the signed-in user — nothing to pass. Sign in (or restore a session) and every
+> request carries that identity.
+
+---
+
+## Authentication
+
+```typescript
+await Koolbase.auth.register({ email: 'user@example.com', password: 'password' });
+
+const session = await Koolbase.auth.login({
+  email: 'user@example.com',
+  password: 'password',
+});
+
+const me = Koolbase.auth.currentUser;
+
+await Koolbase.auth.logout();
+
+await Koolbase.auth.forgotPassword('user@example.com');
+
+const unsubscribe = Koolbase.auth.onAuthStateChange((user) => {
+  console.log(user ? 'signed in' : 'signed out');
+});
+```
+
+### Sessions across page loads
+
+Sessions persist in IndexedDB by default, so a refresh does not sign the user
+out. Restore before rendering:
+
+```typescript
+import { RestoreResult } from '@koolbase/js';
+
+const result = await Koolbase.auth.restoreSession();
+
+switch (result) {
+  case RestoreResult.Restored:  showApp(); break;
+  case RestoreResult.Offline:   showApp(); break;   // optimistic, no network yet
+  case RestoreResult.Expired:   showLogin(); break;
+  case RestoreResult.NoSession: showLogin(); break;
+}
+```
+
+### What browser storage does and does not protect
+
+There is no keychain in a browser. IndexedDB, localStorage and every other
+store a page can read are readable by any script running on that page — so an
+XSS vulnerability in your app exposes the session. This is true of every
+browser SDK from every vendor. The defences are a content-security policy and
+short session lifetimes, not a storage backend.
+
+If your app needs a different trade-off — an httpOnly cookie set by your own
+backend, say — implement `KoolbaseAuthStorage` and pass it as
+`config.authStorage`. The SDK will use yours instead of its own.
+
+### Phone + OTP
+
+```typescript
+await Koolbase.auth.sendOtp({ phoneNumber: '+233200000000' });
+await Koolbase.auth.verifyOtp({ phoneNumber: '+233200000000', code: '123456' });
+```
+
+Configure your SMS provider (Twilio, Africa's Talking, or Hubtel) in the
+dashboard under Phone Auth.
+
+### Google and Apple sign-in
+
+The native sign-in flows are React Native features. In the browser, run the
+provider's web OAuth flow yourself and pass the resulting ID token to
+`Koolbase.auth.signInWithGoogle({ idToken })` or
+`signInWithApple({ identityToken })` — the server-side verification is the
+same.
+
+---
+
+## Database
+
+```typescript
+await Koolbase.db.insert('posts', { title: 'Hello', published: true });
+
+const { records, total } = await Koolbase.db.query('posts', {
+  filters: { published: true },
+  limit: 10,
+  orderBy: 'created_at',
+  orderDesc: true,
+});
+
+const post = records[0];
+console.log(post.data.title);          // your fields live under .data
+console.log(post.id, post.collection); // metadata
+
+await Koolbase.db.update('record-id', { title: 'Updated' });
+await Koolbase.db.delete('record-id');
+```
+
+`total` is the size of the set you are authorized to read, on every page, so
+pagination is exact.
+
+Upsert, bulk delete, atomic batches, populate for related records, and
+semantic / lexical / hybrid search over vectors all work exactly as in
+`@koolbase/react-native` — see its README for the full reference; the API is
+identical.
+
+---
+
+## Offline
+
+Reads come from a local cache when the network is unavailable. `insert`,
+`update` and `delete` queue and send when it returns.
+
+```typescript
+const { records, isFromCache } = await Koolbase.db.query('posts', { limit: 20 });
+
+await Koolbase.db.update(id, { title: 'Corrected' });   // queued if offline
+await Koolbase.db.syncPendingWrites();                   // or wait for reconnect
+
+const pending = await Koolbase.db.pendingWrites();       // for a sync badge
+const conflicts = await Koolbase.db.conflicts();         // writes the server refused
+```
+
+A write the server refuses on replay — because the record changed meanwhile —
+becomes a conflict you resolve: `resolveWithLocal()`, `resolveWithServer()`,
+`resolveWithMerge({...})`, or `abandon()`. Conflicts survive reloads and do not
+expire; surface them if you support offline editing.
+
+**Single tab, in this release.** Two tabs share one IndexedDB and one queue,
+and both may replay the same write. Inserts are idempotent so the damage is
+bounded, but a conflict resolved in one tab can be re-resolved in another.
+Multi-tab coordination is on the roadmap; until then, treat the offline queue
+as belonging to one tab.
+
+---
+
+## Storage
+
+```typescript
+const { object, downloadUrl } = await Koolbase.storage.upload({
+  bucket: 'avatars',
+  path: `user-${userId}.jpg`,
+  file: fileFromInput,              // a File or Blob
+});
+
+const url = await Koolbase.storage.getDownloadUrl('avatars', `user-${userId}.jpg`);
+await Koolbase.storage.delete('avatars', `user-${userId}.jpg`);
+```
+
+Safe-by-default: uploading to a path that is already taken throws
+`KoolbaseStorageConflictError` unless you pass `overwrite: true`. Bucket size
+caps, per-file caps and content-type allowlists arrive as typed errors. Public
+buckets have stable CDN URLs with edge image transforms; versioned buckets keep
+history. Same API as React Native.
+
+---
+
+## Realtime
+
+```typescript
+const unsubscribe = Koolbase.realtime.subscribe('messages', (event) => {
+  if (event.type === 'deleted') console.log('deleted', event.recordId);
+  else console.log(event.type, event.record!.data);
+});
+```
+
+One WebSocket, shared across subscriptions, reconnecting with backoff. Events
+are filtered server-side by the collection's read rule, so a subscriber sees
+only what a query would return them.
+
+---
+
+## Functions
+
+```typescript
+const result = await Koolbase.functions.invoke('send-welcome-email', { userId });
+if (result.success) console.log(result.data);
+```
+
+The signed-in user's token is forwarded automatically; the function reads the
+caller on `ctx.auth`. Failures are typed: `FunctionNotFoundError`,
+`FunctionPermissionError`, `FunctionValidationError`,
+`FunctionQuotaExceededError`, `FunctionExecutionError`.
+
+---
+
+## Feature flags and remote config
+
+```typescript
+if (Koolbase.isEnabled('new_checkout')) { /* ... */ }
+
+const timeout = Koolbase.configNumber('timeout_seconds', 30);
+const apiUrl  = Koolbase.configString('api_url', 'https://api.myapp.com');
+const dark    = Koolbase.configBool('force_dark_mode', false);
+
+const v = Koolbase.checkVersion('1.2.3');
+if (v.status === 'force_update') { /* block and prompt */ }
+```
+
+---
+
+## Analytics
+
+```typescript
+Koolbase.analytics.track('purchase', { value: 1200, currency: 'GHS' });
+Koolbase.analytics.screenView('checkout');
+Koolbase.analytics.identify(user.id);
+Koolbase.analytics.reset();   // on sign-out
+```
+
+Events batch and flush every 30 seconds, when the tab is hidden, and on
+`pagehide`.
+
+---
+
+## Not in the browser package
+
+Stated here so nothing is discovered as a method that fails:
+
+- **Code push** — a native-bundle concept. The web already ships on deploy.
+- **Push messaging** — FCM device tokens come from a native module. Use Web
+  Push through your own service worker and your backend.
+- **Native Google / Apple sign-in** — use the web OAuth flows, above.
+
+---
+
+## Error handling
+
+Every error the SDK raises extends `KoolbaseError`. Authentication failures
+(401) are `KoolbaseUnauthenticatedError` from any subsystem, and the user is
+already signed out by the time you catch one. The full error reference is in
+the [`@koolbase/react-native` README](https://www.npmjs.com/package/@koolbase/react-native#error-handling);
+the classes are identical.
+
+---
+
+## Documentation
+
+Full documentation at [docs.koolbase.com](https://docs.koolbase.com) ·
+Dashboard at [app.koolbase.com](https://app.koolbase.com) ·
+Issues at [github.com/koolbase/koolbase-react-native](https://github.com/koolbase/koolbase-react-native/issues) ·
+Email <dev@koolbase.com>
+
+## License
+
+MIT

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

@@ -0,0 +1,6 @@
+import type { KoolbaseAuthStorage, KoolbaseSession } from '@koolbase/core';
+export declare class BrowserAuthStorage implements KoolbaseAuthStorage {
+    readSession(): Promise<KoolbaseSession | null>;
+    saveSession(session: KoolbaseSession): Promise<void>;
+    clear(): Promise<void>;
+}

package/dist/cjs/auth-storage.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BrowserAuthStorage = void 0;
+const core_1 = require("@koolbase/core");
+// Session persistence for the browser.
+//
+// This is the default when an app injects nothing through
+// KoolbaseConfig.authStorage. It keeps the session in the platform's storage
+// — IndexedDB — so a page refresh does not sign the user out.
+//
+// What it is not: secure the way a keychain is. IndexedDB, localStorage and
+// every other store a page can read are readable by any script running on
+// that page, so an XSS vulnerability in the app exposes the session. That is
+// true of every browser SDK from every vendor; the mitigations are an
+// application's content-security policy and short session lifetimes, not a
+// storage backend. An app that needs a different trade-off — an httpOnly
+// cookie set by its own backend, say — injects its own KoolbaseAuthStorage.
+const KEY = 'koolbase_session_v1';
+class BrowserAuthStorage {
+    async readSession() {
+        const raw = await (0, core_1.getPlatform)().storage.getItem(KEY);
+        if (!raw)
+            return null;
+        try {
+            return JSON.parse(raw);
+        }
+        catch {
+            await this.clear();
+            return null;
+        }
+    }
+    async saveSession(session) {
+        await (0, core_1.getPlatform)().storage.setItem(KEY, JSON.stringify(session));
+    }
+    async clear() {
+        await (0, core_1.getPlatform)().storage.removeItem(KEY);
+    }
+}
+exports.BrowserAuthStorage = BrowserAuthStorage;

package/dist/cjs/index.d.ts

@@ -0,0 +1,18 @@
+export * from '@koolbase/core';
+export { BrowserAuthStorage } from './auth-storage.js';
+export { browserPlatform } from './platform.js';
+import { KoolbaseAuth, KoolbaseDatabase, KoolbaseStorage, KoolbaseRealtime, KoolbaseFunctions, KoolbaseAnalytics, type KoolbaseConfig, type VersionCheckResult } from '@koolbase/core';
+export declare const Koolbase: {
+    initialize(config: KoolbaseConfig): Promise<void>;
+    readonly auth: KoolbaseAuth;
+    readonly db: KoolbaseDatabase;
+    readonly storage: KoolbaseStorage;
+    readonly realtime: KoolbaseRealtime;
+    readonly functions: KoolbaseFunctions;
+    readonly analytics: KoolbaseAnalytics;
+    isEnabled(key: string): boolean;
+    configString(key: string, fallback?: string): string;
+    configNumber(key: string, fallback?: number): number;
+    configBool(key: string, fallback?: boolean): boolean;
+    checkVersion(currentVersion: string): VersionCheckResult;
+};

package/dist/cjs/index.js

@@ -0,0 +1,80 @@
+"use strict";
+// @koolbase/js — composes @koolbase/core for the browser.
+//
+// The same surface as @koolbase/react-native where the browser can honour it.
+// What is deliberately absent, so it is not discovered as a method that
+// fails: code push (a native-bundle concept; the web already has one), the
+// logic engine (its flows arrived only through code-push bundles), push
+// messaging (FCM tokens come from a native module), and Apple/Google native
+// sign-in (use the web OAuth flows against the same auth endpoints).
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Koolbase = exports.browserPlatform = exports.BrowserAuthStorage = void 0;
+__exportStar(require("@koolbase/core"), exports);
+var auth_storage_js_1 = require("./auth-storage.js");
+Object.defineProperty(exports, "BrowserAuthStorage", { enumerable: true, get: function () { return auth_storage_js_1.BrowserAuthStorage; } });
+var platform_js_1 = require("./platform.js");
+Object.defineProperty(exports, "browserPlatform", { enumerable: true, get: function () { return platform_js_1.browserPlatform; } });
+const core_1 = require("@koolbase/core");
+const platform_js_2 = require("./platform.js");
+let _auth = null;
+let _db = null;
+let _storage = null;
+let _realtime = null;
+let _functions = null;
+let _flags = null;
+let _analytics = null;
+let _initialized = false;
+function ensureInitialized() {
+    if (!_initialized) {
+        throw new Error('Koolbase not initialized. Call Koolbase.initialize(config) first.');
+    }
+}
+exports.Koolbase = {
+    async initialize(config) {
+        if (_initialized)
+            return;
+        (0, core_1.setPlatform)(config.platform ?? (0, platform_js_2.browserPlatform)());
+        _auth = new core_1.KoolbaseAuth(config);
+        _db = new core_1.KoolbaseDatabase(config, () => _auth?.currentUser?.id ?? null, () => _auth?.validAccessToken() ?? Promise.resolve(null), async () => { await _auth?.clearStoredSession(); });
+        _storage = new core_1.KoolbaseStorage(config, () => _auth?.validAccessToken() ?? Promise.resolve(null), async () => { await _auth?.clearStoredSession(); });
+        _realtime = new core_1.KoolbaseRealtime(config, () => _auth?.validAccessToken() ?? Promise.resolve(null), () => _auth?.currentUser?.id ?? null);
+        _functions = new core_1.KoolbaseFunctions(config, () => _auth?.validAccessToken() ?? Promise.resolve(null), async () => { await _auth?.clearStoredSession(); });
+        const deviceId = await (0, core_1.getOrCreateDeviceId)();
+        _flags = new core_1.KoolbaseFlags(config, deviceId);
+        if (config.analyticsEnabled !== false) {
+            _analytics = new core_1.KoolbaseAnalytics(config);
+            await _analytics.init(config.appVersion);
+        }
+        _initialized = true;
+    },
+    get auth() { ensureInitialized(); return _auth; },
+    get db() { ensureInitialized(); return _db; },
+    get storage() { ensureInitialized(); return _storage; },
+    get realtime() { ensureInitialized(); return _realtime; },
+    get functions() { ensureInitialized(); return _functions; },
+    get analytics() {
+        ensureInitialized();
+        if (!_analytics)
+            throw new Error('Analytics is disabled (analyticsEnabled: false).');
+        return _analytics;
+    },
+    isEnabled(key) { ensureInitialized(); return _flags.isEnabled(key); },
+    configString(key, fallback = '') { ensureInitialized(); return _flags.getString(key, fallback); },
+    configNumber(key, fallback = 0) { ensureInitialized(); return _flags.getNumber(key, fallback); },
+    configBool(key, fallback = false) { ensureInitialized(); return _flags.getBool(key, fallback); },
+    checkVersion(currentVersion) { ensureInitialized(); return _flags.checkVersion(currentVersion); },
+};

package/dist/cjs/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "commonjs"
+}

package/dist/cjs/platform.d.ts

@@ -0,0 +1,2 @@
+import type { PlatformAdapter } from '@koolbase/core';
+export declare function browserPlatform(): PlatformAdapter;

package/dist/cjs/platform.js

@@ -0,0 +1,145 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.browserPlatform = browserPlatform;
+const auth_storage_js_1 = require("./auth-storage.js");
+// The browser host, expressed through the platform seam.
+//
+// Storage is IndexedDB behind the same four calls the core makes — get, set,
+// remove, list. One object store, string keys, string values, one operation
+// per transaction: exactly the contract the offline queue and conflict store
+// were verified against, with nothing the RN adapter does not also do.
+//
+// What this adapter does NOT do, stated so it is not discovered later:
+//
+//  - Multi-tab coordination. Two tabs share one IndexedDB and one write
+//    queue; both may replay the same pending write. Inserts are idempotent
+//    on the server (ids are UUIDs from birth), so the damage is bounded, but
+//    a conflict resolved in one tab can be re-resolved in another. v1 is
+//    single-tab; a leader election is the fix and belongs in its own change.
+//
+//  - Secure token storage. There is no keychain in a browser. Anything
+//    JavaScript can read, a script injected by XSS can read. The core's
+//    KoolbaseAuthStorage is the injection point; the default here persists
+//    the session in IndexedDB so a refresh does not sign the user out, and
+//    the README says plainly what that means.
+const DB_NAME = 'koolbase';
+const STORE = 'kv';
+function openDB() {
+    return new Promise((resolve, reject) => {
+        const req = indexedDB.open(DB_NAME, 1);
+        req.onupgradeneeded = () => {
+            const db = req.result;
+            if (!db.objectStoreNames.contains(STORE))
+                db.createObjectStore(STORE);
+        };
+        req.onsuccess = () => resolve(req.result);
+        req.onerror = () => reject(req.error ?? new Error('indexedDB open failed'));
+    });
+}
+function tx(db, mode, run) {
+    return new Promise((resolve, reject) => {
+        const t = db.transaction(STORE, mode);
+        const req = run(t.objectStore(STORE));
+        req.onsuccess = () => resolve(req.result);
+        req.onerror = () => reject(req.error ?? new Error('indexedDB request failed'));
+    });
+}
+function indexedDBStorage() {
+    let dbp = null;
+    const db = () => (dbp ?? (dbp = openDB()));
+    return {
+        // Not part of PlatformStorage. Test harnesses call it between cases so
+        // deleteDatabase is not blocked by a live connection.
+        close: async () => {
+            if (!dbp)
+                return;
+            (await dbp).close();
+            dbp = null;
+        },
+        getItem: async (k) => {
+            const v = await tx(await db(), 'readonly', s => s.get(k));
+            return v ?? null;
+        },
+        setItem: async (k, v) => { await tx(await db(), 'readwrite', s => s.put(v, k)); },
+        removeItem: async (k) => { await tx(await db(), 'readwrite', s => s.delete(k)); },
+        getAllKeys: async () => {
+            const keys = await tx(await db(), 'readonly', s => s.getAllKeys());
+            return keys.map(String);
+        },
+    };
+}
+// localStorage is synchronous and small, but present in more environments
+// than IndexedDB (some private modes disable IDB). Used only when IDB is
+// absent, so the common path keeps the larger, asynchronous store.
+function localStorageStorage() {
+    return {
+        getItem: async (k) => localStorage.getItem(k),
+        setItem: async (k, v) => { localStorage.setItem(k, v); },
+        removeItem: async (k) => { localStorage.removeItem(k); },
+        getAllKeys: async () => {
+            const out = [];
+            for (let i = 0; i < localStorage.length; i++) {
+                const k = localStorage.key(i);
+                if (k !== null)
+                    out.push(k);
+            }
+            return out;
+        },
+    };
+}
+function browserVersion() {
+    if (typeof navigator === 'undefined')
+        return '';
+    const ua = navigator.userAgent;
+    const m = /(Chrome|Firefox|Safari|Edg)\/([\d.]+)/.exec(ua);
+    return m ? `${m[1]} ${m[2]}` : '';
+}
+function browserPlatform() {
+    const hasIDB = typeof indexedDB !== 'undefined';
+    return {
+        storage: hasIDB ? indexedDBStorage() : localStorageStorage(),
+        network: {
+            onChange: (cb) => {
+                // navigator.onLine is a hint that the interface is up, not that
+                // Koolbase is reachable. The sync engine treats a false positive as
+                // a failed request, the same as any other; a false negative is only
+                // a delayed flush until the next event or manual sync.
+                // No window in a worker or during SSR: no events, and the sync
+                // engine falls back to discovering reachability by trying.
+                if (typeof window === 'undefined')
+                    return () => { };
+                const on = () => cb(true);
+                const off = () => cb(false);
+                window.addEventListener('online', on);
+                window.addEventListener('offline', off);
+                return () => {
+                    window.removeEventListener('online', on);
+                    window.removeEventListener('offline', off);
+                };
+            },
+        },
+        lifecycle: {
+            onBackground: (cb) => {
+                if (typeof document === 'undefined' || typeof window === 'undefined')
+                    return () => { };
+                const handler = () => { if (document.visibilityState === 'hidden')
+                    cb(); };
+                document.addEventListener('visibilitychange', handler);
+                // pagehide is the reliable "tab is going away" signal on mobile
+                // browsers, where visibilitychange may not fire before unload.
+                window.addEventListener('pagehide', cb);
+                return () => {
+                    document.removeEventListener('visibilitychange', handler);
+                    window.removeEventListener('pagehide', cb);
+                };
+            },
+        },
+        info: {
+            os: 'web',
+            version: browserVersion(),
+        },
+        // IndexedDB-backed; see auth-storage.ts for what that does and does not
+        // protect against.
+        authStorage: () => new auth_storage_js_1.BrowserAuthStorage(),
+    };
+}

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

@@ -0,0 +1,6 @@
+import type { KoolbaseAuthStorage, KoolbaseSession } from '@koolbase/core';
+export declare class BrowserAuthStorage implements KoolbaseAuthStorage {
+    readSession(): Promise<KoolbaseSession | null>;
+    saveSession(session: KoolbaseSession): Promise<void>;
+    clear(): Promise<void>;
+}

package/dist/esm/auth-storage.js

@@ -0,0 +1,35 @@
+import { getPlatform } from '@koolbase/core';
+// Session persistence for the browser.
+//
+// This is the default when an app injects nothing through
+// KoolbaseConfig.authStorage. It keeps the session in the platform's storage
+// — IndexedDB — so a page refresh does not sign the user out.
+//
+// What it is not: secure the way a keychain is. IndexedDB, localStorage and
+// every other store a page can read are readable by any script running on
+// that page, so an XSS vulnerability in the app exposes the session. That is
+// true of every browser SDK from every vendor; the mitigations are an
+// application's content-security policy and short session lifetimes, not a
+// storage backend. An app that needs a different trade-off — an httpOnly
+// cookie set by its own backend, say — injects its own KoolbaseAuthStorage.
+const KEY = 'koolbase_session_v1';
+export class BrowserAuthStorage {
+    async readSession() {
+        const raw = await getPlatform().storage.getItem(KEY);
+        if (!raw)
+            return null;
+        try {
+            return JSON.parse(raw);
+        }
+        catch {
+            await this.clear();
+            return null;
+        }
+    }
+    async saveSession(session) {
+        await getPlatform().storage.setItem(KEY, JSON.stringify(session));
+    }
+    async clear() {
+        await getPlatform().storage.removeItem(KEY);
+    }
+}

package/dist/esm/index.d.ts

@@ -0,0 +1,18 @@
+export * from '@koolbase/core';
+export { BrowserAuthStorage } from './auth-storage.js';
+export { browserPlatform } from './platform.js';
+import { KoolbaseAuth, KoolbaseDatabase, KoolbaseStorage, KoolbaseRealtime, KoolbaseFunctions, KoolbaseAnalytics, type KoolbaseConfig, type VersionCheckResult } from '@koolbase/core';
+export declare const Koolbase: {
+    initialize(config: KoolbaseConfig): Promise<void>;
+    readonly auth: KoolbaseAuth;
+    readonly db: KoolbaseDatabase;
+    readonly storage: KoolbaseStorage;
+    readonly realtime: KoolbaseRealtime;
+    readonly functions: KoolbaseFunctions;
+    readonly analytics: KoolbaseAnalytics;
+    isEnabled(key: string): boolean;
+    configString(key: string, fallback?: string): string;
+    configNumber(key: string, fallback?: number): number;
+    configBool(key: string, fallback?: boolean): boolean;
+    checkVersion(currentVersion: string): VersionCheckResult;
+};

package/dist/esm/index.js

@@ -0,0 +1,61 @@
+// @koolbase/js — composes @koolbase/core for the browser.
+//
+// The same surface as @koolbase/react-native where the browser can honour it.
+// What is deliberately absent, so it is not discovered as a method that
+// fails: code push (a native-bundle concept; the web already has one), the
+// logic engine (its flows arrived only through code-push bundles), push
+// messaging (FCM tokens come from a native module), and Apple/Google native
+// sign-in (use the web OAuth flows against the same auth endpoints).
+export * from '@koolbase/core';
+export { BrowserAuthStorage } from './auth-storage.js';
+export { browserPlatform } from './platform.js';
+import { KoolbaseAuth, KoolbaseDatabase, KoolbaseStorage, KoolbaseRealtime, KoolbaseFunctions, KoolbaseFlags, KoolbaseAnalytics, getOrCreateDeviceId, setPlatform, } from '@koolbase/core';
+import { browserPlatform } from './platform.js';
+let _auth = null;
+let _db = null;
+let _storage = null;
+let _realtime = null;
+let _functions = null;
+let _flags = null;
+let _analytics = null;
+let _initialized = false;
+function ensureInitialized() {
+    if (!_initialized) {
+        throw new Error('Koolbase not initialized. Call Koolbase.initialize(config) first.');
+    }
+}
+export const Koolbase = {
+    async initialize(config) {
+        if (_initialized)
+            return;
+        setPlatform(config.platform ?? browserPlatform());
+        _auth = new KoolbaseAuth(config);
+        _db = new KoolbaseDatabase(config, () => _auth?.currentUser?.id ?? null, () => _auth?.validAccessToken() ?? Promise.resolve(null), async () => { await _auth?.clearStoredSession(); });
+        _storage = new KoolbaseStorage(config, () => _auth?.validAccessToken() ?? Promise.resolve(null), async () => { await _auth?.clearStoredSession(); });
+        _realtime = new KoolbaseRealtime(config, () => _auth?.validAccessToken() ?? Promise.resolve(null), () => _auth?.currentUser?.id ?? null);
+        _functions = new KoolbaseFunctions(config, () => _auth?.validAccessToken() ?? Promise.resolve(null), async () => { await _auth?.clearStoredSession(); });
+        const deviceId = await getOrCreateDeviceId();
+        _flags = new KoolbaseFlags(config, deviceId);
+        if (config.analyticsEnabled !== false) {
+            _analytics = new KoolbaseAnalytics(config);
+            await _analytics.init(config.appVersion);
+        }
+        _initialized = true;
+    },
+    get auth() { ensureInitialized(); return _auth; },
+    get db() { ensureInitialized(); return _db; },
+    get storage() { ensureInitialized(); return _storage; },
+    get realtime() { ensureInitialized(); return _realtime; },
+    get functions() { ensureInitialized(); return _functions; },
+    get analytics() {
+        ensureInitialized();
+        if (!_analytics)
+            throw new Error('Analytics is disabled (analyticsEnabled: false).');
+        return _analytics;
+    },
+    isEnabled(key) { ensureInitialized(); return _flags.isEnabled(key); },
+    configString(key, fallback = '') { ensureInitialized(); return _flags.getString(key, fallback); },
+    configNumber(key, fallback = 0) { ensureInitialized(); return _flags.getNumber(key, fallback); },
+    configBool(key, fallback = false) { ensureInitialized(); return _flags.getBool(key, fallback); },
+    checkVersion(currentVersion) { ensureInitialized(); return _flags.checkVersion(currentVersion); },
+};

package/dist/esm/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}

package/dist/esm/platform.d.ts

@@ -0,0 +1,2 @@
+import type { PlatformAdapter } from '@koolbase/core';
+export declare function browserPlatform(): PlatformAdapter;

package/dist/esm/platform.js

@@ -0,0 +1,142 @@
+import { BrowserAuthStorage } from './auth-storage.js';
+// The browser host, expressed through the platform seam.
+//
+// Storage is IndexedDB behind the same four calls the core makes — get, set,
+// remove, list. One object store, string keys, string values, one operation
+// per transaction: exactly the contract the offline queue and conflict store
+// were verified against, with nothing the RN adapter does not also do.
+//
+// What this adapter does NOT do, stated so it is not discovered later:
+//
+//  - Multi-tab coordination. Two tabs share one IndexedDB and one write
+//    queue; both may replay the same pending write. Inserts are idempotent
+//    on the server (ids are UUIDs from birth), so the damage is bounded, but
+//    a conflict resolved in one tab can be re-resolved in another. v1 is
+//    single-tab; a leader election is the fix and belongs in its own change.
+//
+//  - Secure token storage. There is no keychain in a browser. Anything
+//    JavaScript can read, a script injected by XSS can read. The core's
+//    KoolbaseAuthStorage is the injection point; the default here persists
+//    the session in IndexedDB so a refresh does not sign the user out, and
+//    the README says plainly what that means.
+const DB_NAME = 'koolbase';
+const STORE = 'kv';
+function openDB() {
+    return new Promise((resolve, reject) => {
+        const req = indexedDB.open(DB_NAME, 1);
+        req.onupgradeneeded = () => {
+            const db = req.result;
+            if (!db.objectStoreNames.contains(STORE))
+                db.createObjectStore(STORE);
+        };
+        req.onsuccess = () => resolve(req.result);
+        req.onerror = () => reject(req.error ?? new Error('indexedDB open failed'));
+    });
+}
+function tx(db, mode, run) {
+    return new Promise((resolve, reject) => {
+        const t = db.transaction(STORE, mode);
+        const req = run(t.objectStore(STORE));
+        req.onsuccess = () => resolve(req.result);
+        req.onerror = () => reject(req.error ?? new Error('indexedDB request failed'));
+    });
+}
+function indexedDBStorage() {
+    let dbp = null;
+    const db = () => (dbp ?? (dbp = openDB()));
+    return {
+        // Not part of PlatformStorage. Test harnesses call it between cases so
+        // deleteDatabase is not blocked by a live connection.
+        close: async () => {
+            if (!dbp)
+                return;
+            (await dbp).close();
+            dbp = null;
+        },
+        getItem: async (k) => {
+            const v = await tx(await db(), 'readonly', s => s.get(k));
+            return v ?? null;
+        },
+        setItem: async (k, v) => { await tx(await db(), 'readwrite', s => s.put(v, k)); },
+        removeItem: async (k) => { await tx(await db(), 'readwrite', s => s.delete(k)); },
+        getAllKeys: async () => {
+            const keys = await tx(await db(), 'readonly', s => s.getAllKeys());
+            return keys.map(String);
+        },
+    };
+}
+// localStorage is synchronous and small, but present in more environments
+// than IndexedDB (some private modes disable IDB). Used only when IDB is
+// absent, so the common path keeps the larger, asynchronous store.
+function localStorageStorage() {
+    return {
+        getItem: async (k) => localStorage.getItem(k),
+        setItem: async (k, v) => { localStorage.setItem(k, v); },
+        removeItem: async (k) => { localStorage.removeItem(k); },
+        getAllKeys: async () => {
+            const out = [];
+            for (let i = 0; i < localStorage.length; i++) {
+                const k = localStorage.key(i);
+                if (k !== null)
+                    out.push(k);
+            }
+            return out;
+        },
+    };
+}
+function browserVersion() {
+    if (typeof navigator === 'undefined')
+        return '';
+    const ua = navigator.userAgent;
+    const m = /(Chrome|Firefox|Safari|Edg)\/([\d.]+)/.exec(ua);
+    return m ? `${m[1]} ${m[2]}` : '';
+}
+export function browserPlatform() {
+    const hasIDB = typeof indexedDB !== 'undefined';
+    return {
+        storage: hasIDB ? indexedDBStorage() : localStorageStorage(),
+        network: {
+            onChange: (cb) => {
+                // navigator.onLine is a hint that the interface is up, not that
+                // Koolbase is reachable. The sync engine treats a false positive as
+                // a failed request, the same as any other; a false negative is only
+                // a delayed flush until the next event or manual sync.
+                // No window in a worker or during SSR: no events, and the sync
+                // engine falls back to discovering reachability by trying.
+                if (typeof window === 'undefined')
+                    return () => { };
+                const on = () => cb(true);
+                const off = () => cb(false);
+                window.addEventListener('online', on);
+                window.addEventListener('offline', off);
+                return () => {
+                    window.removeEventListener('online', on);
+                    window.removeEventListener('offline', off);
+                };
+            },
+        },
+        lifecycle: {
+            onBackground: (cb) => {
+                if (typeof document === 'undefined' || typeof window === 'undefined')
+                    return () => { };
+                const handler = () => { if (document.visibilityState === 'hidden')
+                    cb(); };
+                document.addEventListener('visibilitychange', handler);
+                // pagehide is the reliable "tab is going away" signal on mobile
+                // browsers, where visibilitychange may not fire before unload.
+                window.addEventListener('pagehide', cb);
+                return () => {
+                    document.removeEventListener('visibilitychange', handler);
+                    window.removeEventListener('pagehide', cb);
+                };
+            },
+        },
+        info: {
+            os: 'web',
+            version: browserVersion(),
+        },
+        // IndexedDB-backed; see auth-storage.ts for what that does and does not
+        // protect against.
+        authStorage: () => new BrowserAuthStorage(),
+    };
+}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@koolbase/js",
+  "version": "10.0.0",
+  "description": "Koolbase SDK for the browser \u2014 auth, database, storage, realtime, functions, flags and offline sync in one package.",
+  "main": "./dist/cjs/index.js",
+  "types": "./dist/esm/index.d.ts",
+  "files": [
+    "dist",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build": "node ../../scripts/build-package.js js"
+  },
+  "keywords": [
+    "koolbase",
+    "baas",
+    "firebase-alternative",
+    "supabase-alternative",
+    "browser",
+    "typescript"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/koolbase/koolbase-react-native"
+  },
+  "dependencies": {
+    "@koolbase/core": "10.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "module": "./dist/esm/index.js",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/esm/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/index.d.ts",
+        "default": "./dist/cjs/index.js"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "sideEffects": false
+}