lakesync 0.1.6 → 0.2.0

package/dist/client.js

@@ -6,7 +6,7 @@ import {
   decodeSyncResponse,
   encodeSyncPull,
   encodeSyncPush
-} from "./chunk-FHVTUKXL.js";
+} from "./chunk-YHYBLU6W.js";
 import {
   Err,
   HLC,
@@ -22,8 +22,8 @@ import {
   quoteIdentifier,
   toError,
   unwrapOrThrow
-} from "./chunk-P3FT7QCW.js";
-import "./chunk-7D4SUZUM.js";
+} from "./chunk-4SG66H5K.js";
+import "./chunk-DGUM43GV.js";
 
 // ../client/src/db/local-db.ts
 import initSqlJs from "sql.js";
@@ -368,15 +368,19 @@ async function migrateSchema(db, oldSchema, newSchema) {
   });
 }
 
-// ../client/src/queue/memory-queue.ts
-var MemoryQueue = class {
+// ../client/src/queue/memory-outbox.ts
+var MemoryOutbox = class {
   entries = /* @__PURE__ */ new Map();
   counter = 0;
-  /** Add a delta to the queue */
-  async push(delta) {
+  prefix;
+  constructor(prefix = "mem") {
+    this.prefix = prefix;
+  }
+  /** Add an item to the queue. */
+  async push(item) {
     const entry = {
-      id: `mem-${++this.counter}`,
-      delta,
+      id: `${this.prefix}-${++this.counter}`,
+      item,
       status: "pending",
       createdAt: Date.now(),
       retryCount: 0
@@ -384,13 +388,13 @@ var MemoryQueue = class {
     this.entries.set(entry.id, entry);
     return Ok(entry);
   }
-  /** Peek at pending entries (ordered by createdAt), skipping entries with future retryAfter */
+  /** Peek at pending entries (ordered by createdAt), skipping entries with future retryAfter. */
   async peek(limit) {
     const now = Date.now();
     const pending = [...this.entries.values()].filter((e) => e.status === "pending" && (e.retryAfter === void 0 || e.retryAfter <= now)).sort((a, b) => a.createdAt - b.createdAt).slice(0, limit);
     return Ok(pending);
   }
-  /** Mark entries as currently being sent */
+  /** Mark entries as currently being sent. */
   async markSending(ids) {
     for (const id of ids) {
       const entry = this.entries.get(id);
@@ -400,14 +404,14 @@ var MemoryQueue = class {
     }
     return Ok(void 0);
   }
-  /** Acknowledge successful delivery (removes entries) */
+  /** Acknowledge successful delivery (removes entries). */
   async ack(ids) {
     for (const id of ids) {
       this.entries.delete(id);
     }
     return Ok(void 0);
   }
-  /** Negative acknowledge — reset to pending with incremented retryCount and exponential backoff */
+  /** Negative acknowledge — reset to pending with incremented retryCount and exponential backoff. */
   async nack(ids) {
     for (const id of ids) {
       const entry = this.entries.get(id);
@@ -420,18 +424,68 @@ var MemoryQueue = class {
     }
     return Ok(void 0);
   }
-  /** Get the number of pending + sending entries */
+  /** Get the number of pending + sending entries. */
   async depth() {
-    const count = [...this.entries.values()].filter((e) => e.status !== "acked").length;
+    const count = [...this.entries.values()].filter(
+      (e) => e.status === "pending" || e.status === "sending"
+    ).length;
     return Ok(count);
   }
-  /** Remove all entries */
+  /** Remove all entries. */
   async clear() {
     this.entries.clear();
     return Ok(void 0);
   }
 };
 
+// ../client/src/queue/memory-queue.ts
+var MemoryQueue = class {
+  outbox = new MemoryOutbox("mem");
+  /** Add a delta to the queue */
+  async push(delta) {
+    const result = await this.outbox.push(delta);
+    if (!result.ok) return result;
+    return { ok: true, value: this.toQueueEntry(result.value) };
+  }
+  /** Peek at pending entries (ordered by createdAt), skipping entries with future retryAfter */
+  async peek(limit) {
+    const result = await this.outbox.peek(limit);
+    if (!result.ok) return result;
+    return { ok: true, value: result.value.map((e) => this.toQueueEntry(e)) };
+  }
+  /** Mark entries as currently being sent */
+  async markSending(ids) {
+    return this.outbox.markSending(ids);
+  }
+  /** Acknowledge successful delivery (removes entries) */
+  async ack(ids) {
+    return this.outbox.ack(ids);
+  }
+  /** Negative acknowledge — reset to pending with incremented retryCount and exponential backoff */
+  async nack(ids) {
+    return this.outbox.nack(ids);
+  }
+  /** Get the number of pending + sending entries */
+  async depth() {
+    return this.outbox.depth();
+  }
+  /** Remove all entries */
+  async clear() {
+    return this.outbox.clear();
+  }
+  /** Convert a generic OutboxEntry to the SyncQueue-specific QueueEntry shape. */
+  toQueueEntry(entry) {
+    return {
+      id: entry.id,
+      delta: entry.item,
+      status: entry.status,
+      createdAt: entry.createdAt,
+      retryCount: entry.retryCount,
+      retryAfter: entry.retryAfter
+    };
+  }
+};
+
 // ../client/src/queue/idb-queue.ts
 import { openDB as openDB2 } from "idb";
 var DB_NAME = "lakesync-queue";
@@ -574,6 +628,128 @@ var IDBQueue = class {
   }
 };
 
+// ../client/src/sync/action-processor.ts
+var ActionProcessor = class {
+  actionQueue;
+  transport;
+  clientId;
+  hlc;
+  maxRetries;
+  onComplete = null;
+  constructor(config) {
+    this.actionQueue = config.actionQueue;
+    this.transport = config.transport;
+    this.clientId = config.clientId;
+    this.hlc = config.hlc;
+    this.maxRetries = config.maxRetries;
+  }
+  /** Register a callback for action completion events. */
+  setOnComplete(cb) {
+    this.onComplete = cb;
+  }
+  /**
+   * Submit an action for execution.
+   *
+   * Pushes the action to the ActionQueue and triggers immediate processing.
+   */
+  async enqueue(params) {
+    const hlc = this.hlc.now();
+    const { generateActionId } = await import("./src-WU7IBVC4.js");
+    const actionId = await generateActionId({
+      clientId: this.clientId,
+      hlc,
+      connector: params.connector,
+      actionType: params.actionType,
+      params: params.params
+    });
+    const action = {
+      actionId,
+      clientId: this.clientId,
+      hlc,
+      connector: params.connector,
+      actionType: params.actionType,
+      params: params.params,
+      idempotencyKey: params.idempotencyKey
+    };
+    await this.actionQueue.push(action);
+    void this.processQueue();
+  }
+  /**
+   * Process pending actions from the action queue.
+   *
+   * Peeks at pending entries, sends them to the gateway via
+   * `transport.executeAction()`, and acks/nacks based on the result.
+   * Dead-letters entries after `maxRetries` failures.
+   */
+  async processQueue() {
+    if (!this.transport.executeAction) return;
+    const peekResult = await this.actionQueue.peek(100);
+    if (!peekResult.ok || peekResult.value.length === 0) return;
+    const deadLettered = peekResult.value.filter((e) => e.retryCount >= this.maxRetries);
+    const entries = peekResult.value.filter((e) => e.retryCount < this.maxRetries);
+    if (deadLettered.length > 0) {
+      console.warn(
+        `[ActionProcessor] Dead-lettering ${deadLettered.length} actions after ${this.maxRetries} retries`
+      );
+      await this.actionQueue.ack(deadLettered.map((e) => e.id));
+      for (const entry of deadLettered) {
+        this.onComplete?.(entry.action.actionId, {
+          actionId: entry.action.actionId,
+          code: "DEAD_LETTERED",
+          message: `Action dead-lettered after ${this.maxRetries} retries`,
+          retryable: false
+        });
+      }
+    }
+    if (entries.length === 0) return;
+    const ids = entries.map((e) => e.id);
+    await this.actionQueue.markSending(ids);
+    const transportResult = await this.transport.executeAction({
+      clientId: this.clientId,
+      actions: entries.map((e) => e.action)
+    });
+    if (transportResult.ok) {
+      await this.actionQueue.ack(ids);
+      for (const result of transportResult.value.results) {
+        this.onComplete?.(result.actionId, result);
+      }
+      const retryableIds = [];
+      for (let i = 0; i < transportResult.value.results.length; i++) {
+        const result = transportResult.value.results[i];
+        if (isActionError(result) && result.retryable) {
+          retryableIds.push(ids[i]);
+        }
+      }
+    } else {
+      await this.actionQueue.nack(ids);
+    }
+  }
+  /**
+   * Discover available connectors and their supported action types.
+   *
+   * Delegates to the transport's `describeActions()` method. Returns
+   * empty connectors when the transport does not support discovery.
+   */
+  async describeActions() {
+    if (!this.transport.describeActions) {
+      return { ok: true, value: { connectors: {} } };
+    }
+    return this.transport.describeActions();
+  }
+  /**
+   * List available connector types and their configuration schemas.
+   *
+   * Delegates to the transport's `listConnectorTypes()` method. Returns
+   * an empty array when the transport does not support it.
+   */
+  async listConnectorTypes() {
+    if (!this.transport.listConnectorTypes) {
+      return { ok: true, value: [] };
+    }
+    return this.transport.listConnectorTypes();
+  }
+};
+
 // ../client/src/sync/applier.ts
 async function applyRemoteDeltas(db, deltas, resolver, pendingQueue) {
   if (deltas.length === 0) {
@@ -777,6 +953,84 @@ async function applySqlDelta(db, delta) {
   }
 }
 
+// ../client/src/sync/auto-sync.ts
+var AutoSyncScheduler = class {
+  intervalId = null;
+  visibilityHandler = null;
+  syncFn;
+  intervalMs;
+  constructor(syncFn, intervalMs) {
+    this.syncFn = syncFn;
+    this.intervalMs = intervalMs;
+  }
+  /** Whether auto-sync is currently running. */
+  get isRunning() {
+    return this.intervalId !== null;
+  }
+  /** Start periodic syncing and visibility-change-triggered sync. */
+  start() {
+    if (this.intervalId !== null) return;
+    this.intervalId = setInterval(() => {
+      void this.syncFn();
+    }, this.intervalMs);
+    this.setupVisibilitySync();
+  }
+  /** Stop periodic syncing and remove the visibility listener. */
+  stop() {
+    if (this.intervalId !== null) {
+      clearInterval(this.intervalId);
+      this.intervalId = null;
+    }
+    if (this.visibilityHandler) {
+      if (typeof document !== "undefined") {
+        document.removeEventListener("visibilitychange", this.visibilityHandler);
+      }
+      this.visibilityHandler = null;
+    }
+  }
+  /** Register a visibility change listener to sync when the tab becomes visible. */
+  setupVisibilitySync() {
+    this.visibilityHandler = () => {
+      if (typeof document !== "undefined" && document.visibilityState === "visible") {
+        void this.syncFn();
+      }
+    };
+    if (typeof document !== "undefined") {
+      document.addEventListener("visibilitychange", this.visibilityHandler);
+    }
+  }
+};
+
+// ../client/src/sync/strategy.ts
+var PullFirstStrategy = class {
+  async execute(ctx) {
+    if (ctx.syncMode !== "pushOnly") {
+      if (ctx.isFirstSync) {
+        await ctx.initialSync();
+      }
+      await ctx.pull();
+    }
+    if (ctx.syncMode !== "pullOnly") {
+      await ctx.push();
+    }
+    await ctx.processActions();
+  }
+};
+var PushFirstStrategy = class {
+  async execute(ctx) {
+    if (ctx.syncMode !== "pullOnly") {
+      await ctx.push();
+    }
+    if (ctx.syncMode !== "pushOnly") {
+      if (ctx.isFirstSync) {
+        await ctx.initialSync();
+      }
+      await ctx.pull();
+    }
+    await ctx.processActions();
+  }
+};
+
 // ../client/src/sync/tracker.ts
 function rowWithoutId(row) {
   const result = {};
@@ -977,17 +1231,18 @@ var SyncCoordinator = class {
   _clientId;
   maxRetries;
   syncMode;
-  autoSyncIntervalMs;
-  realtimeHeartbeatMs;
   lastSyncedHlc = HLC.encode(0, 0);
   _lastSyncTime = null;
-  syncIntervalId = null;
-  visibilityHandler = null;
   syncing = false;
-  actionQueue;
-  maxActionRetries;
+  _online = true;
+  onlineHandler = null;
+  offlineHandler = null;
+  strategy;
+  autoSyncScheduler;
+  actionProcessor;
   listeners = {
     onChange: [],
+    onSyncStart: [],
     onSyncComplete: [],
     onError: [],
     onActionComplete: []
@@ -1000,11 +1255,26 @@ var SyncCoordinator = class {
     this._clientId = config?.clientId ?? `client-${crypto.randomUUID()}`;
     this.maxRetries = config?.maxRetries ?? 10;
     this.syncMode = config?.syncMode ?? "full";
-    this.autoSyncIntervalMs = config?.autoSyncIntervalMs ?? AUTO_SYNC_INTERVAL_MS;
-    this.realtimeHeartbeatMs = config?.realtimeHeartbeatMs ?? REALTIME_HEARTBEAT_MS;
-    this.actionQueue = config?.actionQueue ?? null;
-    this.maxActionRetries = config?.maxActionRetries ?? 5;
+    this.strategy = config?.strategy ?? new PullFirstStrategy();
     this.tracker = new SyncTracker(db, this.queue, this.hlc, this._clientId);
+    const autoSyncIntervalMs = config?.autoSyncIntervalMs ?? AUTO_SYNC_INTERVAL_MS;
+    const realtimeHeartbeatMs = config?.realtimeHeartbeatMs ?? REALTIME_HEARTBEAT_MS;
+    const intervalMs = transport.supportsRealtime ? realtimeHeartbeatMs : autoSyncIntervalMs;
+    this.autoSyncScheduler = new AutoSyncScheduler(() => this.syncOnce(), intervalMs);
+    if (config?.actionQueue) {
+      this.actionProcessor = new ActionProcessor({
+        actionQueue: config.actionQueue,
+        transport,
+        clientId: this._clientId,
+        hlc: this.hlc,
+        maxRetries: config?.maxActionRetries ?? 5
+      });
+      this.actionProcessor.setOnComplete((actionId, result) => {
+        this.emit("onActionComplete", actionId, result);
+      });
+    } else {
+      this.actionProcessor = null;
+    }
     if (this.transport.onBroadcast) {
       this.transport.onBroadcast((deltas, serverHlc) => {
         void this.handleBroadcast(deltas, serverHlc);
@@ -1017,9 +1287,8 @@ var SyncCoordinator = class {
   }
   /** Remove an event listener */
   off(event, listener) {
-    const arr = this.listeners[event];
-    const idx = arr.indexOf(listener);
-    if (idx !== -1) arr.splice(idx, 1);
+    const listeners = this.listeners;
+    listeners[event] = this.listeners[event].filter((fn) => fn !== listener);
   }
   emit(event, ...args) {
     for (const fn of this.listeners[event]) {
@@ -1029,6 +1298,18 @@ var SyncCoordinator = class {
       }
     }
   }
+  /** Readable snapshot of the current sync state. */
+  get state() {
+    return {
+      syncing: this.syncing,
+      lastSyncTime: this._lastSyncTime,
+      lastSyncedHlc: this.lastSyncedHlc
+    };
+  }
+  /** Whether the client believes it is online. */
+  get isOnline() {
+    return this._online;
+  }
   /** Push pending deltas to the gateway via the transport */
   async pushToGateway() {
     const peekResult = await this.queue.peek(100);
@@ -1130,26 +1411,14 @@ var SyncCoordinator = class {
   }
   /**
    * Start auto-sync: periodic interval + visibility change handler.
-   * Synchronises (push + pull) on tab focus and every 10 seconds.
+   * Synchronises (push + pull) on tab focus and every N seconds.
+   * Registers online/offline listeners to skip sync when offline
+   * and trigger an immediate sync on reconnect.
    */
   startAutoSync() {
     this.transport.connect?.();
-    const intervalMs = this.transport.supportsRealtime ? this.realtimeHeartbeatMs : this.autoSyncIntervalMs;
-    this.syncIntervalId = setInterval(() => {
-      void this.syncOnce();
-    }, intervalMs);
-    this.setupVisibilitySync();
-  }
-  /** Register a visibility change listener to sync on tab focus. */
-  setupVisibilitySync() {
-    this.visibilityHandler = () => {
-      if (typeof document !== "undefined" && document.visibilityState === "visible") {
-        void this.syncOnce();
-      }
-    };
-    if (typeof document !== "undefined") {
-      document.addEventListener("visibilitychange", this.visibilityHandler);
-    }
+    this.autoSyncScheduler.start();
+    this.setupOnlineListeners();
   }
   /**
    * Perform initial sync via checkpoint download.
@@ -1171,21 +1440,25 @@ var SyncCoordinator = class {
     this.lastSyncedHlc = snapshotHlc;
     this._lastSyncTime = /* @__PURE__ */ new Date();
   }
+  /** Build a {@link SyncContext} exposing sync operations for the current cycle. */
+  createSyncContext() {
+    return {
+      isFirstSync: this.lastSyncedHlc === HLC.encode(0, 0),
+      syncMode: this.syncMode,
+      initialSync: () => this.initialSync(),
+      pull: () => this.pullFromGateway(),
+      push: () => this.pushToGateway(),
+      processActions: () => this.processActionQueue()
+    };
+  }
   /** Perform a single sync cycle (push + pull + actions, depending on syncMode). */
   async syncOnce() {
     if (this.syncing) return;
+    if (!this._online) return;
     this.syncing = true;
+    this.emit("onSyncStart");
     try {
-      if (this.syncMode !== "pushOnly") {
-        if (this.lastSyncedHlc === HLC.encode(0, 0)) {
-          await this.initialSync();
-        }
-        await this.pullFromGateway();
-      }
-      if (this.syncMode !== "pullOnly") {
-        await this.pushToGateway();
-      }
-      await this.processActionQueue();
+      await this.strategy.execute(this.createSyncContext());
       this.emit("onSyncComplete");
     } catch (err) {
       this.emit("onError", err instanceof Error ? err : new Error(String(err)));
@@ -1203,84 +1476,20 @@ var SyncCoordinator = class {
    * @param params - Partial action (connector, actionType, params). ActionId and HLC are generated.
    */
   async executeAction(params) {
-    if (!this.actionQueue) {
+    if (!this.actionProcessor) {
       this.emit("onError", new Error("No action queue configured"));
       return;
     }
-    const hlc = this.hlc.now();
-    const { generateActionId } = await import("./src-RHKJFQKR.js");
-    const actionId = await generateActionId({
-      clientId: this._clientId,
-      hlc,
-      connector: params.connector,
-      actionType: params.actionType,
-      params: params.params
-    });
-    const action = {
-      actionId,
-      clientId: this._clientId,
-      hlc,
-      connector: params.connector,
-      actionType: params.actionType,
-      params: params.params,
-      idempotencyKey: params.idempotencyKey
-    };
-    await this.actionQueue.push(action);
-    void this.processActionQueue();
+    await this.actionProcessor.enqueue(params);
   }
   /**
    * Process pending actions from the action queue.
    *
-   * Peeks at pending entries, sends them to the gateway via
-   * `transport.executeAction()`, and acks/nacks based on the result.
-   * Dead-letters entries after `maxActionRetries` failures.
-   * Triggers an immediate `syncOnce()` on success to pull fresh state.
+   * Delegates to the ActionProcessor if one is configured.
    */
   async processActionQueue() {
-    if (!this.actionQueue || !this.transport.executeAction) return;
-    const peekResult = await this.actionQueue.peek(100);
-    if (!peekResult.ok || peekResult.value.length === 0) return;
-    const deadLettered = peekResult.value.filter((e) => e.retryCount >= this.maxActionRetries);
-    const entries = peekResult.value.filter((e) => e.retryCount < this.maxActionRetries);
-    if (deadLettered.length > 0) {
-      console.warn(
-        `[SyncCoordinator] Dead-lettering ${deadLettered.length} actions after ${this.maxActionRetries} retries`
-      );
-      await this.actionQueue.ack(deadLettered.map((e) => e.id));
-      for (const entry of deadLettered) {
-        this.emit("onActionComplete", entry.action.actionId, {
-          actionId: entry.action.actionId,
-          code: "DEAD_LETTERED",
-          message: `Action dead-lettered after ${this.maxActionRetries} retries`,
-          retryable: false
-        });
-      }
-    }
-    if (entries.length === 0) return;
-    const ids = entries.map((e) => e.id);
-    await this.actionQueue.markSending(ids);
-    const transportResult = await this.transport.executeAction({
-      clientId: this._clientId,
-      actions: entries.map((e) => e.action)
-    });
-    if (transportResult.ok) {
-      await this.actionQueue.ack(ids);
-      for (const result of transportResult.value.results) {
-        this.emit("onActionComplete", result.actionId, result);
-      }
-      const retryableIds = [];
-      const ackableIds = [];
-      for (let i = 0; i < transportResult.value.results.length; i++) {
-        const result = transportResult.value.results[i];
-        if (isActionError(result) && result.retryable) {
-          retryableIds.push(ids[i]);
-        } else {
-          ackableIds.push(ids[i]);
-        }
-      }
-    } else {
-      await this.actionQueue.nack(ids);
-    }
+    if (!this.actionProcessor) return;
+    await this.actionProcessor.processQueue();
   }
   /**
    * Discover available connectors and their supported action types.
@@ -1289,6 +1498,9 @@ var SyncCoordinator = class {
    * empty connectors when the transport does not support discovery.
    */
   async describeActions() {
+    if (this.actionProcessor) {
+      return this.actionProcessor.describeActions();
+    }
     if (!this.transport.describeActions) {
       return { ok: true, value: { connectors: {} } };
     }
@@ -1301,6 +1513,9 @@ var SyncCoordinator = class {
    * an empty array when the transport does not support it.
    */
   async listConnectorTypes() {
+    if (this.actionProcessor) {
+      return this.actionProcessor.listConnectorTypes();
+    }
     if (!this.transport.listConnectorTypes) {
       return { ok: true, value: [] };
     }
@@ -1308,17 +1523,40 @@ var SyncCoordinator = class {
   }
   /** Stop auto-sync and clean up listeners */
   stopAutoSync() {
-    if (this.syncIntervalId !== null) {
-      clearInterval(this.syncIntervalId);
-      this.syncIntervalId = null;
+    this.autoSyncScheduler.stop();
+    this.teardownOnlineListeners();
+    this.transport.disconnect?.();
+  }
+  /**
+   * Register window online/offline event listeners.
+   * Guards all browser API access with typeof checks for Node/SSR safety.
+   */
+  setupOnlineListeners() {
+    if (typeof window === "undefined") return;
+    if (typeof navigator !== "undefined" && typeof navigator.onLine === "boolean") {
+      this._online = navigator.onLine;
     }
-    if (this.visibilityHandler) {
-      if (typeof document !== "undefined") {
-        document.removeEventListener("visibilitychange", this.visibilityHandler);
-      }
-      this.visibilityHandler = null;
+    this.onlineHandler = () => {
+      this._online = true;
+      void this.syncOnce();
+    };
+    this.offlineHandler = () => {
+      this._online = false;
+    };
+    window.addEventListener("online", this.onlineHandler);
+    window.addEventListener("offline", this.offlineHandler);
+  }
+  /** Remove online/offline listeners. */
+  teardownOnlineListeners() {
+    if (typeof window === "undefined") return;
+    if (this.onlineHandler) {
+      window.removeEventListener("online", this.onlineHandler);
+      this.onlineHandler = null;
+    }
+    if (this.offlineHandler) {
+      window.removeEventListener("offline", this.offlineHandler);
+      this.offlineHandler = null;
     }
-    this.transport.disconnect?.();
   }
 };
 
@@ -1327,29 +1565,52 @@ var HttpTransport = class {
   baseUrl;
   gatewayId;
   token;
+  getToken;
   _fetch;
   constructor(config) {
     this.baseUrl = config.baseUrl.replace(/\/+$/, "");
     this.gatewayId = config.gatewayId;
     this.token = config.token;
+    this.getToken = config.getToken;
     this._fetch = config.fetch ?? globalThis.fetch.bind(globalThis);
   }
+  /** Resolve the current bearer token, preferring getToken callback over static token. */
+  async resolveToken() {
+    if (this.getToken) {
+      return this.getToken();
+    }
+    return this.token;
+  }
   /**
    * Push local deltas to the remote gateway.
    *
    * Sends a POST request with the push payload as BigInt-safe JSON.
+   * On 401, if `getToken` is configured, refreshes the token and retries once.
    */
   async push(msg) {
     const url = `${this.baseUrl}/sync/${this.gatewayId}/push`;
+    const body = JSON.stringify(msg, bigintReplacer);
     try {
-      const response = await this._fetch(url, {
+      let token = await this.resolveToken();
+      let response = await this._fetch(url, {
         method: "POST",
         headers: {
           "Content-Type": "application/json",
-          Authorization: `Bearer ${this.token}`
+          Authorization: `Bearer ${token}`
         },
-        body: JSON.stringify(msg, bigintReplacer)
+        body
       });
+      if (response.status === 401 && this.getToken) {
+        token = await this.getToken();
+        response = await this._fetch(url, {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${token}`
+          },
+          body
+        });
+      }
       if (!response.ok) {
         const text = await response.text().catch(() => "Unknown error");
         return Err(new LakeSyncError(`Push failed (${response.status}): ${text}`, "TRANSPORT_ERROR"));
@@ -1366,6 +1627,7 @@ var HttpTransport = class {
    * Pull remote deltas from the gateway.
    *
    * Sends a GET request with query parameters for the pull cursor.
+   * On 401, if `getToken` is configured, refreshes the token and retries once.
    */
   async pull(msg) {
     const params = new URLSearchParams({
@@ -1378,12 +1640,22 @@ var HttpTransport = class {
     }
     const url = `${this.baseUrl}/sync/${this.gatewayId}/pull?${params}`;
     try {
-      const response = await this._fetch(url, {
+      let token = await this.resolveToken();
+      let response = await this._fetch(url, {
         method: "GET",
         headers: {
-          Authorization: `Bearer ${this.token}`
+          Authorization: `Bearer ${token}`
         }
       });
+      if (response.status === 401 && this.getToken) {
+        token = await this.getToken();
+        response = await this._fetch(url, {
+          method: "GET",
+          headers: {
+            Authorization: `Bearer ${token}`
+          }
+        });
+      }
       if (!response.ok) {
         const text = await response.text().catch(() => "Unknown error");
         return Err(new LakeSyncError(`Pull failed (${response.status}): ${text}`, "TRANSPORT_ERROR"));
@@ -1403,14 +1675,16 @@ var HttpTransport = class {
    */
   async executeAction(msg) {
     const url = `${this.baseUrl}/sync/${this.gatewayId}/action`;
+    const body = JSON.stringify(msg, bigintReplacer);
     try {
+      const token = await this.resolveToken();
       const response = await this._fetch(url, {
         method: "POST",
         headers: {
           "Content-Type": "application/json",
-          Authorization: `Bearer ${this.token}`
+          Authorization: `Bearer ${token}`
         },
-        body: JSON.stringify(msg, bigintReplacer)
+        body
       });
       if (!response.ok) {
         const text = await response.text().catch(() => "Unknown error");
@@ -1432,10 +1706,11 @@ var HttpTransport = class {
   async describeActions() {
     const url = `${this.baseUrl}/sync/${this.gatewayId}/actions`;
     try {
+      const token = await this.resolveToken();
       const response = await this._fetch(url, {
         method: "GET",
         headers: {
-          Authorization: `Bearer ${this.token}`
+          Authorization: `Bearer ${token}`
         }
       });
       if (!response.ok) {
@@ -1495,10 +1770,11 @@ var HttpTransport = class {
   async checkpoint() {
     const url = `${this.baseUrl}/sync/${this.gatewayId}/checkpoint`;
     try {
+      const token = await this.resolveToken();
       const response = await this._fetch(url, {
         method: "GET",
         headers: {
-          Authorization: `Bearer ${this.token}`,
+          Authorization: `Bearer ${token}`,
           Accept: "application/x-lakesync-checkpoint-stream"
         }
       });
@@ -1728,67 +2004,49 @@ var IDBActionQueue = class {
 
 // ../client/src/queue/memory-action-queue.ts
 var MemoryActionQueue = class {
-  entries = /* @__PURE__ */ new Map();
-  counter = 0;
+  outbox = new MemoryOutbox("mem-action");
   /** Add an action to the queue. */
   async push(action) {
-    const entry = {
-      id: `mem-action-${++this.counter}`,
-      action,
-      status: "pending",
-      createdAt: Date.now(),
-      retryCount: 0
-    };
-    this.entries.set(entry.id, entry);
-    return Ok(entry);
+    const result = await this.outbox.push(action);
+    if (!result.ok) return result;
+    return { ok: true, value: this.toActionEntry(result.value) };
   }
   /** Peek at pending entries (ordered by createdAt), skipping entries with future retryAfter. */
   async peek(limit) {
-    const now = Date.now();
-    const pending = [...this.entries.values()].filter((e) => e.status === "pending" && (e.retryAfter === void 0 || e.retryAfter <= now)).sort((a, b) => a.createdAt - b.createdAt).slice(0, limit);
-    return Ok(pending);
+    const result = await this.outbox.peek(limit);
+    if (!result.ok) return result;
+    return { ok: true, value: result.value.map((e) => this.toActionEntry(e)) };
   }
   /** Mark entries as currently being sent. */
   async markSending(ids) {
-    for (const id of ids) {
-      const entry = this.entries.get(id);
-      if (entry?.status === "pending") {
-        entry.status = "sending";
-      }
-    }
-    return Ok(void 0);
+    return this.outbox.markSending(ids);
   }
   /** Acknowledge successful delivery (removes entries). */
   async ack(ids) {
-    for (const id of ids) {
-      this.entries.delete(id);
-    }
-    return Ok(void 0);
+    return this.outbox.ack(ids);
   }
   /** Negative acknowledge — reset to pending with incremented retryCount and exponential backoff. */
   async nack(ids) {
-    for (const id of ids) {
-      const entry = this.entries.get(id);
-      if (entry) {
-        entry.status = "pending";
-        entry.retryCount++;
-        const backoffMs = Math.min(1e3 * 2 ** entry.retryCount, 3e4);
-        entry.retryAfter = Date.now() + backoffMs;
-      }
-    }
-    return Ok(void 0);
+    return this.outbox.nack(ids);
   }
   /** Get the number of pending + sending entries. */
   async depth() {
-    const count = [...this.entries.values()].filter(
-      (e) => e.status === "pending" || e.status === "sending"
-    ).length;
-    return Ok(count);
+    return this.outbox.depth();
   }
   /** Remove all entries. */
   async clear() {
-    this.entries.clear();
-    return Ok(void 0);
+    return this.outbox.clear();
+  }
+  /** Convert a generic OutboxEntry to the ActionQueue-specific ActionQueueEntry shape. */
+  toActionEntry(entry) {
+    return {
+      id: entry.id,
+      action: entry.item,
+      status: entry.status,
+      createdAt: entry.createdAt,
+      retryCount: entry.retryCount,
+      retryAfter: entry.retryAfter
+    };
   }
 };
 
@@ -1902,6 +2160,10 @@ var LocalTransport = class {
     }
     return Ok(this.gateway.describeActions());
   }
+  /** List available connector types — not supported by local transport. */
+  async listConnectorTypes() {
+    return Ok([]);
+  }
 };
 
 // ../client/src/sync/transport-ws.ts
@@ -1946,7 +2208,7 @@ var WebSocketTransport = class {
   connect() {
     if (this.ws) return;
     this.intentionalClose = false;
-    this.openWebSocket();
+    void this.openWebSocket();
   }
   /** Close the WebSocket connection and stop reconnecting. */
   disconnect() {
@@ -2017,8 +2279,9 @@ var WebSocketTransport = class {
   // -----------------------------------------------------------------------
   // Internal
   // -----------------------------------------------------------------------
-  openWebSocket() {
-    const url = `${this.config.url}?token=${encodeURIComponent(this.config.token)}`;
+  async openWebSocket() {
+    const token = this.config.getToken ? await this.config.getToken() : this.config.token;
+    const url = `${this.config.url}?token=${encodeURIComponent(token)}`;
     this.ws = new WebSocket(url);
     this.ws.binaryType = "arraybuffer";
     this.ws.onopen = () => {
@@ -2075,7 +2338,7 @@ var WebSocketTransport = class {
     this.reconnectAttempts++;
     this.reconnectTimer = setTimeout(() => {
       this.reconnectTimer = null;
-      this.openWebSocket();
+      void this.openWebSocket();
     }, delay);
   }
   sendAndAwaitResponse(frame) {
@@ -2106,6 +2369,8 @@ var WebSocketTransport = class {
   }
 };
 export {
+  ActionProcessor,
+  AutoSyncScheduler,
   DbError,
   HttpTransport,
   IDBActionQueue,
@@ -2113,7 +2378,10 @@ export {
   LocalDB,
   LocalTransport,
   MemoryActionQueue,
+  MemoryOutbox,
   MemoryQueue,
+  PullFirstStrategy,
+  PushFirstStrategy,
   SchemaSynchroniser,
   SyncCoordinator,
   SyncTracker,