lakesync 0.1.6 → 0.2.0

package/dist/compactor.d.ts

@@ -1,6 +1,6 @@
 import { H as HLCTimestamp, R as Result, L as LakeSyncError, F as FlushError } from './result-CojzlFE2.js';
-import { T as TableSchema } from './types-CLlD4XOy.js';
-import { L as LakeAdapter } from './types-DSC_EiwR.js';
+import { L as LakeAdapter } from './adapter-types-DwsQGQS4.js';
+import { T as TableSchema } from './types-BdGBv2ba.js';
 
 /** Configuration for checkpoint generation */
 interface CheckpointConfig {

package/dist/compactor.js

@@ -1,10 +1,10 @@
 import {
   encodeSyncResponse
-} from "./chunk-FHVTUKXL.js";
+} from "./chunk-YHYBLU6W.js";
 import {
   readParquetToDeltas,
   writeDeltasToParquet
-} from "./chunk-SF7Y6ZUA.js";
+} from "./chunk-ZU7RC7CT.js";
 import {
   Err,
   FlushError,
@@ -12,8 +12,8 @@ import {
   LakeSyncError,
   Ok,
   rowKey
-} from "./chunk-P3FT7QCW.js";
-import "./chunk-7D4SUZUM.js";
+} from "./chunk-4SG66H5K.js";
+import "./chunk-DGUM43GV.js";
 
 // ../compactor/src/checkpoint-generator.ts
 var DEFAULT_CHECKPOINT_CONFIG = {

package/dist/connector-jira.d.ts

@@ -1,6 +1,7 @@
+import { B as BaseSourcePoller, P as PushTarget } from './base-poller-Y7ORYgUv.js';
+import { C as ConnectorConfig } from './types-D2C9jTbL.js';
+import { T as TableSchema } from './types-BdGBv2ba.js';
 import { L as LakeSyncError, R as Result } from './result-CojzlFE2.js';
-import { B as BaseSourcePoller, P as PushTarget } from './base-poller-BpUyuG2R.js';
-import { T as TableSchema } from './types-CLlD4XOy.js';
 import './hlc-DiD8QNG3.js';
 
 /** HTTP error from the Jira REST API. */
@@ -228,4 +229,13 @@ declare const JIRA_TABLE_SCHEMAS: ReadonlyArray<TableSchema>;
  */
 declare function testConnection(config: JiraConnectorConfig): Promise<Result<void, JiraApiError | JiraRateLimitError>>;
 
-export { JIRA_TABLE_SCHEMAS, JiraApiError, JiraClient, type JiraComment, type JiraCommentPage, type JiraConnectorConfig, type JiraIngestConfig, type JiraIssue, type JiraProject, type JiraProjectPage, JiraRateLimitError, type JiraSearchResponse, JiraSourcePoller, mapComment, mapIssue, mapProject, testConnection };
+/**
+ * Poller factory for Jira connectors.
+ *
+ * Register with a {@link import("@lakesync/core").PollerRegistry} via `.with("jira", jiraPollerFactory)`.
+ */
+declare function jiraPollerFactory(config: ConnectorConfig, gateway: PushTarget): BaseSourcePoller;
+/** @deprecated Use {@link jiraPollerFactory} instead. */
+declare const createJiraPoller: typeof jiraPollerFactory;
+
+export { JIRA_TABLE_SCHEMAS, JiraApiError, JiraClient, type JiraComment, type JiraCommentPage, type JiraConnectorConfig, type JiraIngestConfig, type JiraIssue, type JiraProject, type JiraProjectPage, JiraRateLimitError, type JiraSearchResponse, JiraSourcePoller, createJiraPoller, jiraPollerFactory, mapComment, mapIssue, mapProject, testConnection };

package/dist/connector-jira.js

@@ -4,19 +4,23 @@ import {
   JiraClient,
   JiraRateLimitError,
   JiraSourcePoller,
+  createJiraPoller,
+  jiraPollerFactory,
   mapComment,
   mapIssue,
   mapProject,
   testConnection
-} from "./chunk-QMS7TGFL.js";
-import "./chunk-P3FT7QCW.js";
-import "./chunk-7D4SUZUM.js";
+} from "./chunk-ZNY4DSFU.js";
+import "./chunk-4SG66H5K.js";
+import "./chunk-DGUM43GV.js";
 export {
   JIRA_TABLE_SCHEMAS,
   JiraApiError,
   JiraClient,
   JiraRateLimitError,
   JiraSourcePoller,
+  createJiraPoller,
+  jiraPollerFactory,
   mapComment,
   mapIssue,
   mapProject,

package/dist/connector-salesforce.d.ts

@@ -1,6 +1,7 @@
+import { B as BaseSourcePoller, P as PushTarget } from './base-poller-Y7ORYgUv.js';
+import { C as ConnectorConfig } from './types-D2C9jTbL.js';
+import { T as TableSchema } from './types-BdGBv2ba.js';
 import { L as LakeSyncError, R as Result } from './result-CojzlFE2.js';
-import { B as BaseSourcePoller, P as PushTarget } from './base-poller-BpUyuG2R.js';
-import { T as TableSchema } from './types-CLlD4XOy.js';
 import './hlc-DiD8QNG3.js';
 
 /** HTTP error from the Salesforce REST API. */
@@ -251,4 +252,13 @@ declare const SALESFORCE_TABLE_SCHEMAS: ReadonlyArray<TableSchema>;
  */
 declare function testConnection(config: SalesforceConnectorConfig): Promise<Result<void, SalesforceAuthError>>;
 
-export { SALESFORCE_TABLE_SCHEMAS, SalesforceApiError, SalesforceAuthError, type SalesforceAuthResponse, SalesforceClient, type SalesforceConnectorConfig, type SalesforceIngestConfig, type SalesforceQueryResponse, SalesforceSourcePoller, type SfAccount, type SfContact, type SfLead, type SfOpportunity, mapAccount, mapContact, mapLead, mapOpportunity, testConnection };
+/**
+ * Poller factory for Salesforce connectors.
+ *
+ * Register with a {@link import("@lakesync/core").PollerRegistry} via `.with("salesforce", salesforcePollerFactory)`.
+ */
+declare function salesforcePollerFactory(config: ConnectorConfig, gateway: PushTarget): BaseSourcePoller;
+/** @deprecated Use {@link salesforcePollerFactory} instead. */
+declare const createSalesforcePoller: typeof salesforcePollerFactory;
+
+export { SALESFORCE_TABLE_SCHEMAS, SalesforceApiError, SalesforceAuthError, type SalesforceAuthResponse, SalesforceClient, type SalesforceConnectorConfig, type SalesforceIngestConfig, type SalesforceQueryResponse, SalesforceSourcePoller, type SfAccount, type SfContact, type SfLead, type SfOpportunity, createSalesforcePoller, mapAccount, mapContact, mapLead, mapOpportunity, salesforcePollerFactory, testConnection };

package/dist/connector-salesforce.js

@@ -4,24 +4,28 @@ import {
   SalesforceAuthError,
   SalesforceClient,
   SalesforceSourcePoller,
+  createSalesforcePoller,
   mapAccount,
   mapContact,
   mapLead,
   mapOpportunity,
+  salesforcePollerFactory,
   testConnection
-} from "./chunk-NCZYFZ3B.js";
-import "./chunk-P3FT7QCW.js";
-import "./chunk-7D4SUZUM.js";
+} from "./chunk-XVP5DJJ7.js";
+import "./chunk-4SG66H5K.js";
+import "./chunk-DGUM43GV.js";
 export {
   SALESFORCE_TABLE_SCHEMAS,
   SalesforceApiError,
   SalesforceAuthError,
   SalesforceClient,
   SalesforceSourcePoller,
+  createSalesforcePoller,
   mapAccount,
   mapContact,
   mapLead,
   mapOpportunity,
+  salesforcePollerFactory,
   testConnection
 };
 //# sourceMappingURL=connector-salesforce.js.map

package/dist/{coordinator-D32a5rNk.d.ts → coordinator-eGmZMnJ_.d.ts}

@@ -1,8 +1,8 @@
 import { L as LakeSyncError, R as Result, H as HLCTimestamp } from './result-CojzlFE2.js';
 import { A as Action, i as ActionPush, j as ActionResponse, d as ActionDiscovery, k as ActionResult, e as ActionErrorResult } from './types-Bs-QyOe-.js';
 import { H as HLC } from './hlc-DiD8QNG3.js';
-import { a as ConnectorDescriptor } from './registry-CPTgO9jv.js';
-import { R as RowDelta, S as SyncPush, b as SyncPull, c as SyncResponse } from './types-CLlD4XOy.js';
+import { a as ConnectorDescriptor } from './registry-Dd8JuW8T.js';
+import { R as RowDelta, S as SyncPush, e as SyncPull, f as SyncResponse } from './types-BdGBv2ba.js';
 
 /** Configuration for opening a local database */
 interface DbConfig {
@@ -154,6 +154,54 @@ interface ActionQueue {
     clear(): Promise<Result<void, LakeSyncError>>;
 }
 
+/**
+ * Context provided to sync strategies with access to sync operations.
+ *
+ * Each method performs a single sync operation. The strategy decides
+ * ordering and which operations to perform.
+ */
+interface SyncContext {
+    /** Whether this is the first sync (lastSyncedHlc === 0). */
+    readonly isFirstSync: boolean;
+    /** Current sync mode. */
+    readonly syncMode: "full" | "pushOnly" | "pullOnly";
+    /** Perform initial sync via checkpoint download. */
+    initialSync(): Promise<void>;
+    /** Pull remote deltas from the gateway. */
+    pull(): Promise<number>;
+    /** Push local deltas to the gateway. */
+    push(): Promise<void>;
+    /** Process pending actions from the action queue. */
+    processActions(): Promise<void>;
+}
+/**
+ * Strategy that determines the ordering of sync operations.
+ *
+ * Decouples "what to sync" from "in what order".
+ */
+interface SyncStrategy {
+    /** Execute a sync cycle using the provided context. */
+    execute(ctx: SyncContext): Promise<void>;
+}
+/**
+ * Default strategy: pull before push.
+ *
+ * On first sync, performs initial sync (checkpoint download).
+ * Then pulls remote deltas, pushes local deltas, and processes actions.
+ */
+declare class PullFirstStrategy implements SyncStrategy {
+    execute(ctx: SyncContext): Promise<void>;
+}
+/**
+ * Push-first strategy for offline-first apps.
+ *
+ * Pushes local deltas first, then pulls remote deltas.
+ * Useful when local changes should be sent before receiving updates.
+ */
+declare class PushFirstStrategy implements SyncStrategy {
+    execute(ctx: SyncContext): Promise<void>;
+}
+
 /**
  * Tracks local mutations (insert, update, delete) and produces
  * column-level deltas that are pushed to a SyncQueue.
@@ -224,7 +272,7 @@ interface CheckpointResponse {
     /** Snapshot HLC marking the point-in-time of this checkpoint */
     snapshotHlc: HLCTimestamp;
 }
-/** Abstract transport layer for communicating with a remote sync gateway */
+/** Core sync transport — push and pull deltas. */
 interface SyncTransport {
     /** Push local deltas to the gateway */
     push(msg: SyncPush): Promise<Result<{
@@ -233,30 +281,57 @@ interface SyncTransport {
     }, LakeSyncError>>;
     /** Pull remote deltas from the gateway */
     pull(msg: SyncPull): Promise<Result<SyncResponse, LakeSyncError>>;
+}
+/** Transport that supports checkpoint downloads for initial sync. */
+interface CheckpointTransport {
     /** Download checkpoint for initial sync. Returns null if no checkpoint available. */
-    checkpoint?(): Promise<Result<CheckpointResponse | null, LakeSyncError>>;
-    /** Execute imperative actions against external systems via the gateway. */
-    executeAction?(msg: ActionPush): Promise<Result<ActionResponse, LakeSyncError>>;
-    /** Discover available connectors and their supported action types. */
-    describeActions?(): Promise<Result<ActionDiscovery, LakeSyncError>>;
-    /** List available connector types and their configuration schemas. */
-    listConnectorTypes?(): Promise<Result<ConnectorDescriptor[], LakeSyncError>>;
+    checkpoint(): Promise<Result<CheckpointResponse | null, LakeSyncError>>;
+}
+/** Transport that supports real-time server-initiated broadcasts. */
+interface RealtimeTransport {
     /** Whether this transport supports real-time server push. */
-    readonly supportsRealtime?: boolean;
+    readonly supportsRealtime: boolean;
     /** Register callback for server-initiated broadcasts. */
-    onBroadcast?(callback: (deltas: RowDelta[], serverHlc: HLCTimestamp) => void): void;
+    onBroadcast(callback: (deltas: RowDelta[], serverHlc: HLCTimestamp) => void): void;
     /** Connect persistent transport (e.g. open WebSocket). */
-    connect?(): void;
+    connect(): void;
     /** Disconnect persistent transport (e.g. close WebSocket). */
-    disconnect?(): void;
+    disconnect(): void;
 }
+/** Transport that supports imperative action execution. */
+interface ActionTransport {
+    /** Execute imperative actions against external systems via the gateway. */
+    executeAction(msg: ActionPush): Promise<Result<ActionResponse, LakeSyncError>>;
+    /** Discover available connectors and their supported action types. */
+    describeActions(): Promise<Result<ActionDiscovery, LakeSyncError>>;
+    /** List available connector types and their configuration schemas. */
+    listConnectorTypes(): Promise<Result<ConnectorDescriptor[], LakeSyncError>>;
+}
+/**
+ * Union type combining the core sync transport with optional capabilities.
+ *
+ * Transports must implement push/pull. Checkpoint, real-time, and action
+ * capabilities are opt-in via the respective interfaces.
+ */
+type TransportWithCapabilities = SyncTransport & Partial<CheckpointTransport> & Partial<RealtimeTransport> & Partial<ActionTransport>;
 
 /** Controls which operations syncOnce() / startAutoSync() performs */
 type SyncMode = "full" | "pushOnly" | "pullOnly";
+/** Readable snapshot of the coordinator's current sync state. */
+interface SyncState {
+    /** Whether a sync cycle is currently in progress. */
+    syncing: boolean;
+    /** Last successful sync time, or null if never synced. */
+    lastSyncTime: Date | null;
+    /** HLC timestamp of the last successfully synced delta. */
+    lastSyncedHlc: HLCTimestamp;
+}
 /** Events emitted by SyncCoordinator */
 interface SyncEvents {
     /** Fired after remote deltas are applied locally. Count is the number of deltas applied. */
     onChange: (count: number) => void;
+    /** Fired when a sync cycle (push + pull) begins. */
+    onSyncStart: () => void;
     /** Fired after a successful sync cycle (push + pull) completes. */
     onSyncComplete: () => void;
     /** Fired when a sync error occurs. */
@@ -284,12 +359,17 @@ interface SyncCoordinatorConfig {
     actionQueue?: ActionQueue;
     /** Maximum retries for actions before dead-lettering. Defaults to 5. */
     maxActionRetries?: number;
+    /** Sync strategy. Defaults to PullFirstStrategy. */
+    strategy?: SyncStrategy;
 }
 /**
  * Coordinates local mutations (via SyncTracker) with gateway push/pull.
  *
- * Uses a {@link SyncTransport} abstraction to communicate with the gateway,
+ * Uses a {@link TransportWithCapabilities} abstraction to communicate with the gateway,
  * allowing both in-process (LocalTransport) and remote (HttpTransport) usage.
+ *
+ * Delegates auto-sync scheduling to {@link AutoSyncScheduler} and action
+ * processing to {@link ActionProcessor}.
  */
 declare class SyncCoordinator {
     readonly tracker: SyncTracker;
@@ -301,22 +381,26 @@ declare class SyncCoordinator {
     private readonly _clientId;
     private readonly maxRetries;
     private readonly syncMode;
-    private readonly autoSyncIntervalMs;
-    private readonly realtimeHeartbeatMs;
     private lastSyncedHlc;
     private _lastSyncTime;
-    private syncIntervalId;
-    private visibilityHandler;
     private syncing;
-    private readonly actionQueue;
-    private readonly maxActionRetries;
+    private _online;
+    private onlineHandler;
+    private offlineHandler;
+    private readonly strategy;
+    private readonly autoSyncScheduler;
+    private readonly actionProcessor;
     private listeners;
-    constructor(db: LocalDB, transport: SyncTransport, config?: SyncCoordinatorConfig);
+    constructor(db: LocalDB, transport: TransportWithCapabilities, config?: SyncCoordinatorConfig);
     /** Register an event listener */
     on<K extends keyof SyncEvents>(event: K, listener: SyncEvents[K]): void;
     /** Remove an event listener */
     off<K extends keyof SyncEvents>(event: K, listener: SyncEvents[K]): void;
     private emit;
+    /** Readable snapshot of the current sync state. */
+    get state(): SyncState;
+    /** Whether the client believes it is online. */
+    get isOnline(): boolean;
     /** Push pending deltas to the gateway via the transport */
     pushToGateway(): Promise<void>;
     /**
@@ -344,11 +428,11 @@ declare class SyncCoordinator {
     get lastSyncTime(): Date | null;
     /**
      * 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(): void;
-    /** Register a visibility change listener to sync on tab focus. */
-    private setupVisibilitySync;
     /**
      * Perform initial sync via checkpoint download.
      *
@@ -359,6 +443,8 @@ declare class SyncCoordinator {
      * not support checkpoints, falls back to incremental pull.
      */
     private initialSync;
+    /** Build a {@link SyncContext} exposing sync operations for the current cycle. */
+    private createSyncContext;
     /** Perform a single sync cycle (push + pull + actions, depending on syncMode). */
     syncOnce(): Promise<void>;
     /**
@@ -379,10 +465,7 @@ declare class SyncCoordinator {
     /**
      * 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.
      */
     processActionQueue(): Promise<void>;
     /**
@@ -401,6 +484,13 @@ declare class SyncCoordinator {
     listConnectorTypes(): Promise<Result<ConnectorDescriptor[], LakeSyncError>>;
     /** Stop auto-sync and clean up listeners */
     stopAutoSync(): void;
+    /**
+     * Register window online/offline event listeners.
+     * Guards all browser API access with typeof checks for Node/SSR safety.
+     */
+    private setupOnlineListeners;
+    /** Remove online/offline listeners. */
+    private teardownOnlineListeners;
 }
 
-export { type ActionQueue as A, type CheckpointResponse as C, DbError as D, LocalDB as L, type QueueEntry as Q, type SyncQueue as S, type Transaction as T, type SyncCoordinatorConfig as a, SyncCoordinator as b, type SyncTransport as c, type ActionQueueEntry as d, type ActionQueueEntryStatus as e, type DbConfig as f, type QueueEntryStatus as g, type SyncEvents as h, type SyncMode as i, SyncTracker as j };
+export { type ActionQueue as A, type CheckpointTransport as C, DbError as D, LocalDB as L, PullFirstStrategy as P, type QueueEntry as Q, type RealtimeTransport as R, type SyncQueue as S, type TransportWithCapabilities as T, type SyncCoordinatorConfig as a, SyncCoordinator as b, type ActionQueueEntry as c, type SyncTransport as d, type ActionTransport as e, type CheckpointResponse as f, type ActionQueueEntryStatus as g, type DbConfig as h, PushFirstStrategy as i, type QueueEntryStatus as j, type SyncContext as k, type SyncEvents as l, type SyncMode as m, type SyncState as n, type SyncStrategy as o, SyncTracker as p, type Transaction as q };

package/dist/create-poller-Cc2MGfhh.d.ts

@@ -0,0 +1,55 @@
+import { R as Result } from './result-CojzlFE2.js';
+import { P as PushTarget, B as BaseSourcePoller } from './base-poller-Y7ORYgUv.js';
+import { C as ConnectorConfig } from './types-D2C9jTbL.js';
+
+/** Claims extracted from a verified JWT token */
+interface AuthClaims {
+    /** Client identifier (from JWT `sub` claim) */
+    clientId: string;
+    /** Authorised gateway ID (from JWT `gw` claim) */
+    gatewayId: string;
+    /** Role for route-level access control (from JWT `role` claim, defaults to "client") */
+    role: string;
+    /** Non-standard JWT claims for sync rule evaluation */
+    customClaims: Record<string, string | string[]>;
+}
+/** Authentication error returned when JWT verification fails */
+declare class AuthError extends Error {
+    constructor(message: string);
+}
+/**
+ * Verify a JWT token signed with HMAC-SHA256 and extract authentication claims.
+ *
+ * Uses the Web Crypto API exclusively (no external dependencies), making it
+ * suitable for Cloudflare Workers and other edge runtimes.
+ *
+ * @param token - The raw JWT string (header.payload.signature)
+ * @param secret - The HMAC-SHA256 secret key
+ * @returns A Result containing AuthClaims on success, or AuthError on failure
+ */
+declare function verifyToken(token: string, secret: string): Promise<Result<AuthClaims, AuthError>>;
+
+/** Factory function that creates a poller from a ConnectorConfig. */
+type PollerFactory = (config: ConnectorConfig, gateway: PushTarget) => BaseSourcePoller;
+/** Immutable registry of poller factories keyed by connector type. */
+interface PollerRegistry {
+    /** Look up a factory by type. */
+    get(type: string): PollerFactory | undefined;
+    /** Create a new registry with an additional or replaced factory. */
+    with(type: string, factory: PollerFactory): PollerRegistry;
+}
+/**
+ * Create an immutable {@link PollerRegistry} from a Map of factories.
+ */
+declare function createPollerRegistry(factories?: Map<string, PollerFactory>): PollerRegistry;
+/**
+ * Create a poller from a {@link ConnectorConfig}.
+ *
+ * @param config - Connector configuration.
+ * @param gateway - Push target for the poller.
+ * @param registry - Registry of poller factories to look up the config's type.
+ * @throws If no factory has been registered for the config's `type`.
+ */
+declare function createPoller(config: ConnectorConfig, gateway: PushTarget, registry: PollerRegistry): BaseSourcePoller;
+
+export { type AuthClaims as A, type PollerFactory as P, AuthError as a, type PollerRegistry as b, createPoller as c, createPollerRegistry as d, verifyToken as v };

package/dist/factory-DFfR-030.d.ts

@@ -0,0 +1,33 @@
+import { R as Result, A as AdapterError } from './result-CojzlFE2.js';
+import { D as DatabaseAdapter } from './adapter-types-DwsQGQS4.js';
+import { C as ConnectorConfig } from './types-D2C9jTbL.js';
+
+/** Factory function that creates a DatabaseAdapter from a ConnectorConfig. */
+type AdapterFactory = (config: ConnectorConfig) => DatabaseAdapter;
+/** Immutable registry of adapter factories keyed by connector type. */
+interface AdapterFactoryRegistry {
+    /** Look up a factory by type. */
+    get(type: string): AdapterFactory | undefined;
+    /** Create a new registry with an additional or replaced factory. */
+    with(type: string, factory: AdapterFactory): AdapterFactoryRegistry;
+}
+/**
+ * Create an immutable {@link AdapterFactoryRegistry} from a Map of factories.
+ */
+declare function createAdapterFactoryRegistry(factories?: Map<string, AdapterFactory>): AdapterFactoryRegistry;
+/** Default registry with built-in database adapters (Postgres, MySQL, BigQuery). */
+declare function defaultAdapterFactoryRegistry(): AdapterFactoryRegistry;
+/**
+ * Instantiate a {@link DatabaseAdapter} from a {@link ConnectorConfig}.
+ *
+ * Uses the provided registry (or the default built-in registry) to look up
+ * a factory for the config's type. Returns an {@link AdapterError} if the
+ * type is unsupported or the adapter constructor throws.
+ *
+ * @param config - Validated connector configuration.
+ * @param registry - Optional adapter factory registry. Defaults to built-in adapters.
+ * @returns The instantiated adapter or an error.
+ */
+declare function createDatabaseAdapter(config: ConnectorConfig, registry?: AdapterFactoryRegistry): Result<DatabaseAdapter, AdapterError>;
+
+export { type AdapterFactory as A, type AdapterFactoryRegistry as a, createDatabaseAdapter as b, createAdapterFactoryRegistry as c, defaultAdapterFactoryRegistry as d };