@koolbase/core 10.1.0 → 10.3.0

package/dist/cjs/analytics.d.ts

@@ -4,13 +4,27 @@ export declare class KoolbaseAnalytics {
     private queue;
     private deviceId;
     private userId?;
+    private getSignedInUser?;
     private environmentId?;
     private userProperties;
     private sessionId;
     private appVersion;
     private flushTimer?;
     private initialized;
-    constructor(config: KoolbaseConfig);
+    /**
+     * getSignedInUser lets events carry the signed-in user without the app
+     * having to say so.
+     *
+     * identify() existed and nothing errored when an app never called it, so
+     * every event landed anonymous and retention, funnels and per-user
+     * analysis were quietly worthless — found in a real project as 53 events,
+     * 8 registered users and not one event carrying a user id. The Flutter SDK
+     * fixed this in 11.2.0; the TypeScript SDKs kept the bug until now.
+     *
+     * identify() still wins, for an app with its own identity system, and
+     * reset() releases that override.
+     */
+    constructor(config: KoolbaseConfig, getSignedInUser?: () => string | null);
     init(appVersion?: string): Promise<void>;
     track(eventName: string, properties?: Record<string, unknown>): void;
     screenView(screenName: string, properties?: Record<string, unknown>): void;

package/dist/cjs/analytics.js

@@ -9,7 +9,20 @@ const DEVICE_ID_KEY = 'koolbase:device_id';
 const FLUSH_INTERVAL_MS = 30000;
 const MAX_BATCH_SIZE = 20;
 class KoolbaseAnalytics {
-    constructor(config) {
+    /**
+     * getSignedInUser lets events carry the signed-in user without the app
+     * having to say so.
+     *
+     * identify() existed and nothing errored when an app never called it, so
+     * every event landed anonymous and retention, funnels and per-user
+     * analysis were quietly worthless — found in a real project as 53 events,
+     * 8 registered users and not one event carrying a user id. The Flutter SDK
+     * fixed this in 11.2.0; the TypeScript SDKs kept the bug until now.
+     *
+     * identify() still wins, for an app with its own identity system, and
+     * reset() releases that override.
+     */
+    constructor(config, getSignedInUser) {
         this.queue = [];
         this.deviceId = '';
         this.userProperties = {};
@@ -17,6 +30,7 @@ class KoolbaseAnalytics {
         this.appVersion = '1.0.0';
         this.initialized = false;
         this.config = config;
+        this.getSignedInUser = getSignedInUser;
     }
     // ─── Init ─────────────────────────────────────────────────────────────────
     async init(appVersion) {
@@ -42,7 +56,8 @@ class KoolbaseAnalytics {
     track(eventName, properties) {
         const event = {
             device_id: this.deviceId,
-            user_id: this.userId,
+            // The explicit override first, then whoever is signed in.
+            user_id: this.userId ?? this.getSignedInUser?.() ?? undefined,
             environment_id: this.environmentId,
             event_name: eventName,
             properties: properties ?? {},

package/dist/cjs/index.d.ts

@@ -19,4 +19,4 @@ export { getOrCreateDeviceId } from './device-id.js';
 export { koolbaseSdkVersion } from './device-metadata.js';
 export { RestoreResult } from './types.js';
 export type { AuthStateListener, FetchLike, KoolbaseAuthStorage } from './types.js';
-export { setPlatform, getPlatform, memoryPlatform, type PlatformAdapter, type PlatformStorage, type PlatformNetwork, type PlatformLifecycle, type PlatformInfo, } from './platform.js';
+export { setPlatform, getPlatform, memoryPlatform, type PlatformAdapter, type PlatformStorage, type PlatformNetwork, type PlatformLifecycle, type PlatformLocks, type PlatformInfo, } from './platform.js';

package/dist/cjs/offline-state.d.ts

@@ -70,6 +70,14 @@ export interface OfflineState {
 export declare class OfflineStateTooLargeError extends Error {
     constructor(bytes: number);
 }
+/**
+ * Lock names derive from the storage key they protect, so the two cannot
+ * drift apart. Note what the key does NOT carry: a project id. Two Koolbase
+ * apps on one origin with the same user id already share offline state —
+ * a pre-existing collision these locks neither create nor fix.
+ */
+export declare function stateLockName(userId: string): string;
+export declare function flushLockName(userId: string): string;
 export declare function readOfflineState(userId: string): Promise<OfflineState>;
 /**
  * Reads, mutates, and writes the state under the user's lock.

package/dist/cjs/offline-state.js

@@ -2,6 +2,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.OfflineStateTooLargeError = void 0;
 exports.recordKey = recordKey;
+exports.stateLockName = stateLockName;
+exports.flushLockName = flushLockName;
 exports.readOfflineState = readOfflineState;
 exports.mutateOfflineState = mutateOfflineState;
 exports.queueWrite = queueWrite;
@@ -72,6 +74,18 @@ function byteLength(s) {
     return bytes;
 }
 const locks = () => (0, shared_js_1.shared)('locks', () => new Map());
+/**
+ * Lock names derive from the storage key they protect, so the two cannot
+ * drift apart. Note what the key does NOT carry: a project id. Two Koolbase
+ * apps on one origin with the same user id already share offline state —
+ * a pre-existing collision these locks neither create nor fix.
+ */
+function stateLockName(userId) {
+    return `${stateKey(userId)}:lock`;
+}
+function flushLockName(userId) {
+    return `${stateKey(userId)}:flush`;
+}
 async function withLock(userId, fn) {
     const previous = locks().get(userId) ?? Promise.resolve();
     let release = () => { };
@@ -79,7 +93,10 @@ async function withLock(userId, fn) {
     locks().set(userId, previous.then(() => next));
     await previous;
     try {
-        return await fn();
+        // In-process first, then across copies of the app that share this store.
+        // Both are needed: the promise chain orders callers within one runtime,
+        // the platform lock orders runtimes.
+        return await (0, platform_js_1.getPlatform)().locks.exclusive(stateLockName(userId), fn);
     }
     finally {
         release();

package/dist/cjs/platform.d.ts

@@ -17,6 +17,31 @@ export interface PlatformLifecycle {
     /** Subscribe to the app moving to the background. Used to flush analytics. */
     onBackground(callback: () => void): () => void;
 }
+/**
+ * Coordination between copies of the SDK that share durable storage.
+ *
+ * Two locks, different problems, different durations:
+ *
+ *   exclusive     short, waited for, held across a read-modify-write of the
+ *                 offline state and never across the network. Stops one copy
+ *                 overwriting another's queued write.
+ *
+ *   tryExclusive  a lease on the responsibility to replay the queue, held for
+ *                 a whole flush pass INCLUDING its HTTP calls, and never
+ *                 waited for. Without it two tabs read the same pending write
+ *                 and both send it: the state stays consistent and the server
+ *                 is hit twice. A copy that cannot take the lease skips,
+ *                 because whoever holds it is already doing the work.
+ *
+ * A host where the SDK cannot be running twice over one store — React Native,
+ * one process — satisfies both by just running the function.
+ */
+export interface PlatformLocks {
+    exclusive<T>(name: string, fn: () => Promise<T>): Promise<T>;
+    tryExclusive(name: string, fn: () => Promise<void>): Promise<{
+        ran: boolean;
+    }>;
+}
 export interface PlatformInfo {
     /** e.g. 'ios', 'android', 'web' */
     os: string;
@@ -28,6 +53,7 @@ export interface PlatformAdapter {
     network: PlatformNetwork;
     lifecycle: PlatformLifecycle;
     info: PlatformInfo;
+    locks: PlatformLocks;
     /**
      * The host's best persistent store for the auth session, or null if it has
      * none worth the name. Used only when the app injects nothing through

package/dist/cjs/platform.js

@@ -28,6 +28,12 @@ function memoryPlatform() {
             onBackground: () => () => { },
         },
         info: { os: 'memory', version: '' },
+        // One process, one store, and the in-process promise chain in
+        // offline-state already serialises it.
+        locks: {
+            exclusive: (_n, fn) => fn(),
+            tryExclusive: async (_n, fn) => { await fn(); return { ran: true }; },
+        },
         authStorage: () => null,
     };
 }

package/dist/cjs/sync-engine.d.ts

@@ -18,6 +18,9 @@ export declare class SyncEngine {
     start(): void;
     stop(): void;
     flush(): Promise<void>;
+    private recheckTimer;
+    private scheduleRecheck;
+    private flushHeld;
     /**
      * Sends one queued write, returning the revision the record now carries.
      *

package/dist/cjs/sync-engine.js

@@ -45,6 +45,7 @@ class RevisionMismatch extends Error {
 class SyncEngine {
     constructor(config, getUserId, getToken, onSyncComplete, onSessionExpired) {
         this.isSyncing = false;
+        this.recheckTimer = null;
         this.config = config;
         this.getUserId = getUserId;
         this.getToken = getToken;
@@ -66,6 +67,32 @@ class SyncEngine {
         const userId = this.getUserId();
         if (!userId)
             return;
+        // A lease on replaying this user's queue, held for the whole pass
+        // including its HTTP calls. isSyncing does this within one runtime; this
+        // does it across every copy sharing the store. Not waited for: a copy
+        // that cannot take it skips, because the holder is replaying the same
+        // queue — waiting would duplicate the wait, not the work.
+        const { ran } = await (0, platform_js_1.getPlatform)().locks.tryExclusive((0, offline_state_js_1.flushLockName)(userId), () => this.flushHeld(userId));
+        if (!ran) {
+            // Skipped, and a write queued between the holder's last read and its
+            // release would otherwise sit until an unrelated reconnect. Re-check
+            // once, after the holder has had time to finish; if it is still
+            // running, its own recheck covers what we would have sent.
+            this.scheduleRecheck();
+        }
+    }
+    scheduleRecheck() {
+        // Bounded and coalesced: one pending recheck at a time, so a page with
+        // several tabs cannot turn a skipped flush into a retry storm.
+        if (this.recheckTimer)
+            return;
+        this.recheckTimer = setTimeout(() => {
+            this.recheckTimer = null;
+            void this.flush();
+        }, 1500);
+        this.recheckTimer.unref?.();
+    }
+    async flushHeld(userId) {
         this.isSyncing = true;
         try {
             // Before anything is sent. Writes queued by an earlier version sit under a

package/dist/esm/analytics.d.ts

@@ -4,13 +4,27 @@ export declare class KoolbaseAnalytics {
     private queue;
     private deviceId;
     private userId?;
+    private getSignedInUser?;
     private environmentId?;
     private userProperties;
     private sessionId;
     private appVersion;
     private flushTimer?;
     private initialized;
-    constructor(config: KoolbaseConfig);
+    /**
+     * getSignedInUser lets events carry the signed-in user without the app
+     * having to say so.
+     *
+     * identify() existed and nothing errored when an app never called it, so
+     * every event landed anonymous and retention, funnels and per-user
+     * analysis were quietly worthless — found in a real project as 53 events,
+     * 8 registered users and not one event carrying a user id. The Flutter SDK
+     * fixed this in 11.2.0; the TypeScript SDKs kept the bug until now.
+     *
+     * identify() still wins, for an app with its own identity system, and
+     * reset() releases that override.
+     */
+    constructor(config: KoolbaseConfig, getSignedInUser?: () => string | null);
     init(appVersion?: string): Promise<void>;
     track(eventName: string, properties?: Record<string, unknown>): void;
     screenView(screenName: string, properties?: Record<string, unknown>): void;

package/dist/esm/analytics.js

@@ -6,7 +6,20 @@ const DEVICE_ID_KEY = 'koolbase:device_id';
 const FLUSH_INTERVAL_MS = 30000;
 const MAX_BATCH_SIZE = 20;
 export class KoolbaseAnalytics {
-    constructor(config) {
+    /**
+     * getSignedInUser lets events carry the signed-in user without the app
+     * having to say so.
+     *
+     * identify() existed and nothing errored when an app never called it, so
+     * every event landed anonymous and retention, funnels and per-user
+     * analysis were quietly worthless — found in a real project as 53 events,
+     * 8 registered users and not one event carrying a user id. The Flutter SDK
+     * fixed this in 11.2.0; the TypeScript SDKs kept the bug until now.
+     *
+     * identify() still wins, for an app with its own identity system, and
+     * reset() releases that override.
+     */
+    constructor(config, getSignedInUser) {
         this.queue = [];
         this.deviceId = '';
         this.userProperties = {};
@@ -14,6 +27,7 @@ export class KoolbaseAnalytics {
         this.appVersion = '1.0.0';
         this.initialized = false;
         this.config = config;
+        this.getSignedInUser = getSignedInUser;
     }
     // ─── Init ─────────────────────────────────────────────────────────────────
     async init(appVersion) {
@@ -39,7 +53,8 @@ export class KoolbaseAnalytics {
     track(eventName, properties) {
         const event = {
             device_id: this.deviceId,
-            user_id: this.userId,
+            // The explicit override first, then whoever is signed in.
+            user_id: this.userId ?? this.getSignedInUser?.() ?? undefined,
             environment_id: this.environmentId,
             event_name: eventName,
             properties: properties ?? {},

package/dist/esm/index.d.ts

@@ -19,4 +19,4 @@ export { getOrCreateDeviceId } from './device-id.js';
 export { koolbaseSdkVersion } from './device-metadata.js';
 export { RestoreResult } from './types.js';
 export type { AuthStateListener, FetchLike, KoolbaseAuthStorage } from './types.js';
-export { setPlatform, getPlatform, memoryPlatform, type PlatformAdapter, type PlatformStorage, type PlatformNetwork, type PlatformLifecycle, type PlatformInfo, } from './platform.js';
+export { setPlatform, getPlatform, memoryPlatform, type PlatformAdapter, type PlatformStorage, type PlatformNetwork, type PlatformLifecycle, type PlatformLocks, type PlatformInfo, } from './platform.js';

package/dist/esm/offline-state.d.ts

@@ -70,6 +70,14 @@ export interface OfflineState {
 export declare class OfflineStateTooLargeError extends Error {
     constructor(bytes: number);
 }
+/**
+ * Lock names derive from the storage key they protect, so the two cannot
+ * drift apart. Note what the key does NOT carry: a project id. Two Koolbase
+ * apps on one origin with the same user id already share offline state —
+ * a pre-existing collision these locks neither create nor fix.
+ */
+export declare function stateLockName(userId: string): string;
+export declare function flushLockName(userId: string): string;
 export declare function readOfflineState(userId: string): Promise<OfflineState>;
 /**
  * Reads, mutates, and writes the state under the user's lock.

package/dist/esm/offline-state.js

@@ -63,6 +63,18 @@ function byteLength(s) {
     return bytes;
 }
 const locks = () => shared('locks', () => new Map());
+/**
+ * Lock names derive from the storage key they protect, so the two cannot
+ * drift apart. Note what the key does NOT carry: a project id. Two Koolbase
+ * apps on one origin with the same user id already share offline state —
+ * a pre-existing collision these locks neither create nor fix.
+ */
+export function stateLockName(userId) {
+    return `${stateKey(userId)}:lock`;
+}
+export function flushLockName(userId) {
+    return `${stateKey(userId)}:flush`;
+}
 async function withLock(userId, fn) {
     const previous = locks().get(userId) ?? Promise.resolve();
     let release = () => { };
@@ -70,7 +82,10 @@ async function withLock(userId, fn) {
     locks().set(userId, previous.then(() => next));
     await previous;
     try {
-        return await fn();
+        // In-process first, then across copies of the app that share this store.
+        // Both are needed: the promise chain orders callers within one runtime,
+        // the platform lock orders runtimes.
+        return await getPlatform().locks.exclusive(stateLockName(userId), fn);
     }
     finally {
         release();

package/dist/esm/platform.d.ts

@@ -17,6 +17,31 @@ export interface PlatformLifecycle {
     /** Subscribe to the app moving to the background. Used to flush analytics. */
     onBackground(callback: () => void): () => void;
 }
+/**
+ * Coordination between copies of the SDK that share durable storage.
+ *
+ * Two locks, different problems, different durations:
+ *
+ *   exclusive     short, waited for, held across a read-modify-write of the
+ *                 offline state and never across the network. Stops one copy
+ *                 overwriting another's queued write.
+ *
+ *   tryExclusive  a lease on the responsibility to replay the queue, held for
+ *                 a whole flush pass INCLUDING its HTTP calls, and never
+ *                 waited for. Without it two tabs read the same pending write
+ *                 and both send it: the state stays consistent and the server
+ *                 is hit twice. A copy that cannot take the lease skips,
+ *                 because whoever holds it is already doing the work.
+ *
+ * A host where the SDK cannot be running twice over one store — React Native,
+ * one process — satisfies both by just running the function.
+ */
+export interface PlatformLocks {
+    exclusive<T>(name: string, fn: () => Promise<T>): Promise<T>;
+    tryExclusive(name: string, fn: () => Promise<void>): Promise<{
+        ran: boolean;
+    }>;
+}
 export interface PlatformInfo {
     /** e.g. 'ios', 'android', 'web' */
     os: string;
@@ -28,6 +53,7 @@ export interface PlatformAdapter {
     network: PlatformNetwork;
     lifecycle: PlatformLifecycle;
     info: PlatformInfo;
+    locks: PlatformLocks;
     /**
      * The host's best persistent store for the auth session, or null if it has
      * none worth the name. Used only when the app injects nothing through

package/dist/esm/platform.js

@@ -23,6 +23,12 @@ export function memoryPlatform() {
             onBackground: () => () => { },
         },
         info: { os: 'memory', version: '' },
+        // One process, one store, and the in-process promise chain in
+        // offline-state already serialises it.
+        locks: {
+            exclusive: (_n, fn) => fn(),
+            tryExclusive: async (_n, fn) => { await fn(); return { ran: true }; },
+        },
         authStorage: () => null,
     };
 }

package/dist/esm/sync-engine.d.ts

@@ -18,6 +18,9 @@ export declare class SyncEngine {
     start(): void;
     stop(): void;
     flush(): Promise<void>;
+    private recheckTimer;
+    private scheduleRecheck;
+    private flushHeld;
     /**
      * Sends one queued write, returning the revision the record now carries.
      *

package/dist/esm/sync-engine.js

@@ -1,4 +1,4 @@
-import { readOfflineState, mutateOfflineState, migrateLegacyQueue, } from './offline-state.js';
+import { readOfflineState, mutateOfflineState, migrateLegacyQueue, flushLockName, } from './offline-state.js';
 import { KoolbaseUnauthenticatedError } from './errors.js';
 import { getPlatform } from './platform.js';
 import { invalidateCache, removeCachedRecord, } from './cache-store.js';
@@ -42,6 +42,7 @@ class RevisionMismatch extends Error {
 export class SyncEngine {
     constructor(config, getUserId, getToken, onSyncComplete, onSessionExpired) {
         this.isSyncing = false;
+        this.recheckTimer = null;
         this.config = config;
         this.getUserId = getUserId;
         this.getToken = getToken;
@@ -63,6 +64,32 @@ export class SyncEngine {
         const userId = this.getUserId();
         if (!userId)
             return;
+        // A lease on replaying this user's queue, held for the whole pass
+        // including its HTTP calls. isSyncing does this within one runtime; this
+        // does it across every copy sharing the store. Not waited for: a copy
+        // that cannot take it skips, because the holder is replaying the same
+        // queue — waiting would duplicate the wait, not the work.
+        const { ran } = await getPlatform().locks.tryExclusive(flushLockName(userId), () => this.flushHeld(userId));
+        if (!ran) {
+            // Skipped, and a write queued between the holder's last read and its
+            // release would otherwise sit until an unrelated reconnect. Re-check
+            // once, after the holder has had time to finish; if it is still
+            // running, its own recheck covers what we would have sent.
+            this.scheduleRecheck();
+        }
+    }
+    scheduleRecheck() {
+        // Bounded and coalesced: one pending recheck at a time, so a page with
+        // several tabs cannot turn a skipped flush into a retry storm.
+        if (this.recheckTimer)
+            return;
+        this.recheckTimer = setTimeout(() => {
+            this.recheckTimer = null;
+            void this.flush();
+        }, 1500);
+        this.recheckTimer.unref?.();
+    }
+    async flushHeld(userId) {
         this.isSyncing = true;
         try {
             // Before anything is sent. Writes queued by an earlier version sit under a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@koolbase/core",
-  "version": "10.1.0",
+  "version": "10.3.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",