@syncular/client 0.0.6-136 → 0.0.6-138

package/src/engine/SyncEngine.ts

@@ -37,6 +37,7 @@ import type {
   ConflictInfo,
   OutboxStats,
   PresenceEntry,
+  PushResultInfo,
   RealtimeTransportLike,
   SubscriptionProgress,
   SyncAwaitBootstrapOptions,
@@ -313,6 +314,7 @@ export class SyncEngine<DB extends SyncClientDb = SyncClientDb> {
   };
   private activeBootstrapSubscriptions = new Set<string>();
   private bootstrapStartedAt = new Map<string, number>();
+  private emittedConflictIds = new Set<string>();
   private inspectorEvents: SyncInspectorEvent[] = [];
   private nextInspectorEventId = 1;
 
@@ -1133,6 +1135,49 @@ export class SyncEngine<DB extends SyncClientDb = SyncClientDb> {
     }
   }
 
+  private emitPushResult(result: PushResultInfo): void {
+    this.emit('push:result', result);
+    this.config.onPushResult?.(result);
+  }
+
+  private async emitNewConflicts(): Promise<void> {
+    const conflicts = await this.getConflicts();
+    const activeIds = new Set(conflicts.map((conflict) => conflict.id));
+
+    for (const id of this.emittedConflictIds) {
+      if (!activeIds.has(id)) {
+        this.emittedConflictIds.delete(id);
+      }
+    }
+
+    const sorted = [...conflicts].sort((left, right) => {
+      if (left.createdAt !== right.createdAt) {
+        return left.createdAt - right.createdAt;
+      }
+      return left.opIndex - right.opIndex;
+    });
+
+    for (const conflict of sorted) {
+      if (this.emittedConflictIds.has(conflict.id)) {
+        continue;
+      }
+      this.emittedConflictIds.add(conflict.id);
+      this.emit('conflict:new', conflict);
+      this.config.onConflict?.(conflict);
+    }
+  }
+
+  private async emitNewConflictsSafe(context: string): Promise<void> {
+    try {
+      await this.emitNewConflicts();
+    } catch (error) {
+      console.warn(
+        `[SyncEngine] Failed to emit conflict:new during ${context}`,
+        error
+      );
+    }
+  }
+
   private async resolveResetTargets(
     options: SyncResetOptions
   ): Promise<SubscriptionState[]> {
@@ -1279,6 +1324,9 @@ export class SyncEngine<DB extends SyncClientDb = SyncClientDb> {
 
     this.resetLocalState();
     await this.refreshOutboxStats();
+    if (result.deletedConflicts > 0) {
+      this.emittedConflictIds.clear();
+    }
     this.updateState({ error: null });
 
     return result;
@@ -1446,6 +1494,9 @@ export class SyncEngine<DB extends SyncClientDb = SyncClientDb> {
                 }
               );
               pushed = result.pushed;
+              if (result.pushResult) {
+                this.emitPushResult(result.pushResult);
+              }
             }
           }
         } catch {
@@ -1636,6 +1687,10 @@ export class SyncEngine<DB extends SyncClientDb = SyncClientDb> {
           )
       );
 
+      for (const pushResult of result.pushResults) {
+        this.emitPushResult(pushResult);
+      }
+
       const syncResult: SyncResult = {
         success: true,
         pushedCommits: result.pushedCommits,
@@ -1674,6 +1729,7 @@ export class SyncEngine<DB extends SyncClientDb = SyncClientDb> {
         this.emitDataChange(changedTables);
       }
       this.handleBootstrapLifecycle(result.pullResponse);
+      await this.emitNewConflictsSafe('sync success');
 
       // Refresh outbox stats (fire-and-forget — don't block sync:complete)
       this.refreshOutboxStats().catch((error) => {
@@ -1732,6 +1788,7 @@ export class SyncEngine<DB extends SyncClientDb = SyncClientDb> {
       });
 
       this.handleError(error);
+      await this.emitNewConflictsSafe('sync error');
 
       const durationMs = Math.max(0, Date.now() - startedAtMs);
       countSyncMetric('sync.client.sync.results', 1, {
@@ -1797,9 +1854,17 @@ export class SyncEngine<DB extends SyncClientDb = SyncClientDb> {
    */
   private async applyWsDeliveredChanges(
     changes: SyncChange[],
-    cursor: number
+    cursor: number,
+    metadata?: {
+      commitSeq?: number;
+      actorId?: string | null;
+      createdAt?: string | null;
+    }
   ): Promise<boolean> {
     try {
+      const commitSeq = metadata?.commitSeq ?? cursor;
+      const actorId = metadata?.actorId ?? null;
+      const createdAt = metadata?.createdAt ?? null;
       await this.config.db.transaction().execute(async (trx) => {
         for (const change of changes) {
           const handler = getClientHandler(this.config.handlers, change.table);
@@ -1808,7 +1873,15 @@ export class SyncEngine<DB extends SyncClientDb = SyncClientDb> {
               `Missing client table handler for WS change table "${change.table}"`
             );
           }
-          await handler.applyChange({ trx }, change);
+          await handler.applyChange(
+            {
+              trx,
+              commitSeq,
+              actorId,
+              createdAt,
+            },
+            change
+          );
         }
 
         // Update subscription cursors
@@ -1851,7 +1924,12 @@ export class SyncEngine<DB extends SyncClientDb = SyncClientDb> {
    */
   private async handleWsDelivery(
     changes: SyncChange[],
-    cursor: number
+    cursor: number,
+    metadata?: {
+      commitSeq?: number;
+      actorId?: string | null;
+      createdAt?: string | null;
+    }
   ): Promise<void> {
     // If a sync is already in-flight, let it handle everything
     if (this.syncPromise) {
@@ -1895,7 +1973,11 @@ export class SyncEngine<DB extends SyncClientDb = SyncClientDb> {
 
     // Apply changes + update cursor
     const inlineApplyStartedAtMs = Date.now();
-    const applied = await this.applyWsDeliveredChanges(changes, cursor);
+    const applied = await this.applyWsDeliveredChanges(
+      changes,
+      cursor,
+      metadata
+    );
     const inlineApplyDurationMs = Math.max(
       0,
       Date.now() - inlineApplyStartedAtMs
@@ -2161,10 +2243,27 @@ export class SyncEngine<DB extends SyncClientDb = SyncClientDb> {
           const hasInlineChanges =
             Array.isArray(event.data.changes) && event.data.changes.length > 0;
           const cursor = event.data.cursor;
+          const commitSeqRaw = event.data.commitSeq;
+          const commitSeq =
+            typeof commitSeqRaw === 'number'
+              ? commitSeqRaw
+              : typeof cursor === 'number'
+                ? cursor
+                : undefined;
+          const actorId =
+            typeof event.data.actorId === 'string' ? event.data.actorId : null;
+          const createdAt =
+            typeof event.data.createdAt === 'string'
+              ? event.data.createdAt
+              : null;
 
           if (hasInlineChanges && typeof cursor === 'number') {
             // WS delivered changes + cursor — may skip HTTP pull
-            this.handleWsDelivery(event.data.changes as SyncChange[], cursor);
+            this.handleWsDelivery(event.data.changes as SyncChange[], cursor, {
+              commitSeq,
+              actorId,
+              createdAt,
+            });
           } else {
             // Cursor-only wake-up or no cursor — must HTTP sync
             countSyncMetric('sync.client.ws.delivery.events', 1, {

package/src/engine/types.ts

@@ -140,14 +140,28 @@ export type SyncEventType =
   | 'sync:complete'
   | 'sync:live'
   | 'sync:error'
+  | 'push:result'
   | 'bootstrap:start'
   | 'bootstrap:progress'
   | 'bootstrap:complete'
   | 'connection:change'
   | 'outbox:change'
   | 'data:change'
+  | 'conflict:new'
   | 'presence:change';
 
+export type PushResultStatus = 'applied' | 'cached' | 'rejected' | 'retriable';
+
+export interface PushResultInfo {
+  outboxCommitId: string;
+  clientCommitId: string;
+  status: PushResultStatus;
+  commitSeq: number | null;
+  results: SyncPushResponse['results'];
+  errorCode: string | null;
+  timestamp: number;
+}
+
 /**
  * Presence entry for a client connected to a scope
  */
@@ -172,6 +186,7 @@ export interface SyncEventPayloads {
   };
   'sync:live': { timestamp: number };
   'sync:error': SyncError;
+  'push:result': PushResultInfo;
   'bootstrap:start': {
     timestamp: number;
     stateId: string;
@@ -203,6 +218,7 @@ export interface SyncEventPayloads {
     scopes: string[];
     timestamp: number;
   };
+  'conflict:new': ConflictInfo;
   'presence:change': {
     scopeKey: string;
     presence: PresenceEntry[];
@@ -260,6 +276,8 @@ export interface SyncEngineConfig<DB extends SyncClientDb = SyncClientDb> {
   onError?: (error: SyncError) => void;
   /** Conflict callback */
   onConflict?: (conflict: ConflictInfo) => void;
+  /** Per-commit push outcome callback */
+  onPushResult?: (result: PushResultInfo) => void;
   /** Data change callback */
   onDataChange?: (scopes: string[]) => void;
   /**
@@ -317,8 +335,11 @@ export interface RealtimeTransportLike extends SyncTransport {
       event: string;
       data: {
         cursor?: number;
+        commitSeq?: number;
         changes?: unknown[];
         error?: string;
+        actorId?: string;
+        createdAt?: string;
         timestamp: number;
       };
     }) => void,

package/src/handlers/types.ts

@@ -16,6 +16,15 @@ import type { Transaction } from 'kysely';
 export interface ClientHandlerContext<DB> {
   /** Database transaction */
   trx: Transaction<DB>;
+  /**
+   * Commit metadata for server-delivered changes.
+   * Undefined for local optimistic changes.
+   */
+  commitSeq?: number | null;
+  /** Actor that authored the server commit, when available. */
+  actorId?: string | null;
+  /** Commit creation timestamp (ISO string), when available. */
+  createdAt?: string | null;
 }
 
 /**

package/src/pull-engine.test.ts

@@ -818,4 +818,98 @@ describe('applyPullResponse chunk streaming', () => {
       .executeTakeFirst();
     expect(Number(state?.cursor ?? -1)).toBe(2);
   });
+
+  it('passes commit metadata to applyChange handler context', async () => {
+    const transport: SyncTransport = {
+      async sync() {
+        return {};
+      },
+      async fetchSnapshotChunk() {
+        return new Uint8Array();
+      },
+    };
+
+    const appliedContexts: Array<{
+      commitSeq: number | null | undefined;
+      actorId: string | null | undefined;
+      createdAt: string | null | undefined;
+    }> = [];
+
+    const handlers: ClientHandlerCollection<TestDb> = [
+      {
+        table: 'items',
+        async applySnapshot() {},
+        async clearAll() {},
+        async applyChange(ctx) {
+          appliedContexts.push({
+            commitSeq: ctx.commitSeq,
+            actorId: ctx.actorId,
+            createdAt: ctx.createdAt,
+          });
+        },
+      },
+    ];
+
+    const options = {
+      clientId: 'client-1',
+      subscriptions: [
+        {
+          id: 'items-sub',
+          table: 'items',
+          scopes: {},
+        },
+      ],
+      stateId: 'default',
+    };
+
+    const pullState = await buildPullRequest(db, options);
+    const response: SyncPullResponse = {
+      ok: true,
+      subscriptions: [
+        {
+          id: 'items-sub',
+          status: 'active',
+          scopes: {},
+          bootstrap: false,
+          bootstrapState: null,
+          nextCursor: 7,
+          commits: [
+            {
+              commitSeq: 7,
+              actorId: 'remote-user',
+              createdAt: '2026-02-28T12:00:00.000Z',
+              changes: [
+                {
+                  table: 'items',
+                  row_id: 'item-ctx',
+                  op: 'upsert',
+                  row_version: 1,
+                  row_json: { id: 'item-ctx', name: 'ctx-test' },
+                  scopes: {},
+                },
+              ],
+            },
+          ],
+          snapshots: [],
+        },
+      ],
+    };
+
+    await applyPullResponse(
+      db,
+      transport,
+      handlers,
+      options,
+      pullState,
+      response
+    );
+
+    expect(appliedContexts).toEqual([
+      {
+        commitSeq: 7,
+        actorId: 'remote-user',
+        createdAt: '2026-02-28T12:00:00.000Z',
+      },
+    ]);
+  });
 });

package/src/pull-engine.ts

@@ -888,9 +888,20 @@ export async function applyPullResponse<DB extends SyncClientDb>(
       } else {
         // Apply incremental changes
         for (const commit of sub.commits) {
+          const commitSeq = commit.commitSeq ?? null;
+          const actorId = commit.actorId ?? null;
+          const createdAt = commit.createdAt ?? null;
           for (const change of commit.changes) {
             const handler = getClientHandlerOrThrow(handlers, change.table);
-            await handler.applyChange({ trx }, change);
+            await handler.applyChange(
+              {
+                trx,
+                commitSeq,
+                actorId,
+                createdAt,
+              },
+              change
+            );
           }
         }
       }

package/src/push-engine.ts

@@ -10,6 +10,7 @@ import type {
 import { countSyncMetric } from '@syncular/core';
 import type { Kysely } from 'kysely';
 import { upsertConflictsForRejectedCommit } from './conflicts';
+import type { PushResultInfo } from './engine/types';
 import {
   getNextSendableOutboxCommit,
   markOutboxCommitAcked,
@@ -31,6 +32,7 @@ export interface SyncPushOnceOptions {
 export interface SyncPushOnceResult {
   pushed: boolean;
   response?: SyncPushResponse;
+  pushResult?: PushResultInfo;
 }
 
 interface TransportWithWsPush extends SyncTransport {
@@ -48,6 +50,41 @@ function clonePushRequest(request: SyncPushRequest): SyncPushRequest {
   return JSON.parse(JSON.stringify(request)) as SyncPushRequest;
 }
 
+function firstPushErrorCode(response: SyncPushResponse): string | null {
+  const firstError = response.results.find(
+    (result) => result.status === 'error'
+  );
+  if (
+    firstError &&
+    'code' in firstError &&
+    typeof firstError.code === 'string' &&
+    firstError.code
+  ) {
+    return firstError.code;
+  }
+  const hasConflict = response.results.some(
+    (result) => result.status === 'conflict'
+  );
+  return hasConflict ? 'CONFLICT' : null;
+}
+
+function buildPushResult(args: {
+  outboxCommitId: string;
+  clientCommitId: string;
+  status: PushResultInfo['status'];
+  response: SyncPushResponse;
+}): PushResultInfo {
+  return {
+    outboxCommitId: args.outboxCommitId,
+    clientCommitId: args.clientCommitId,
+    status: args.status,
+    commitSeq: args.response.commitSeq ?? null,
+    results: args.response.results,
+    errorCode: firstPushErrorCode(args.response),
+    timestamp: Date.now(),
+  };
+}
+
 export async function syncPushOnce<DB extends SyncClientDb>(
   db: Kysely<DB>,
   transport: SyncTransport,
@@ -178,7 +215,16 @@ export async function syncPushOnce<DB extends SyncClientDb>(
       commitSeq: responseToUse.commitSeq ?? null,
       responseJson,
     });
-    return { pushed: true, response: responseToUse };
+    return {
+      pushed: true,
+      response: responseToUse,
+      pushResult: buildPushResult({
+        outboxCommitId: next.id,
+        clientCommitId: next.client_commit_id,
+        status: responseToUse.status,
+        response: responseToUse,
+      }),
+    };
   }
 
   // Check if all errors are retriable - if so, keep pending for retry
@@ -198,7 +244,16 @@ export async function syncPushOnce<DB extends SyncClientDb>(
       error: `Retriable: ${errorMessages}`,
       responseJson,
     });
-    return { pushed: true, response: responseToUse };
+    return {
+      pushed: true,
+      response: responseToUse,
+      pushResult: buildPushResult({
+        outboxCommitId: next.id,
+        clientCommitId: next.client_commit_id,
+        status: 'retriable',
+        response: responseToUse,
+      }),
+    };
   }
 
   // Terminal rejection - mark as failed and record conflicts
@@ -212,5 +267,14 @@ export async function syncPushOnce<DB extends SyncClientDb>(
     error: 'REJECTED',
     responseJson,
   });
-  return { pushed: true, response: responseToUse };
+  return {
+    pushed: true,
+    response: responseToUse,
+    pushResult: buildPushResult({
+      outboxCommitId: next.id,
+      clientCommitId: next.client_commit_id,
+      status: 'rejected',
+      response: responseToUse,
+    }),
+  };
 }

package/src/sync-loop.ts

@@ -15,6 +15,7 @@ import type {
 } from '@syncular/core';
 import type { Kysely } from 'kysely';
 import { upsertConflictsForRejectedCommit } from './conflicts';
+import type { PushResultInfo } from './engine/types';
 import type { ClientHandlerCollection } from './handlers/collection';
 import {
   getNextSendableOutboxCommit,
@@ -41,6 +42,42 @@ interface SyncPushUntilSettledOptions extends SyncPushOnceOptions {
 
 interface SyncPushUntilSettledResult {
   pushedCount: number;
+  pushResults: PushResultInfo[];
+}
+
+function firstPushErrorCode(response: SyncPushResponse): string | null {
+  const firstError = response.results.find(
+    (result) => result.status === 'error'
+  );
+  if (
+    firstError &&
+    'code' in firstError &&
+    typeof firstError.code === 'string' &&
+    firstError.code
+  ) {
+    return firstError.code;
+  }
+  const hasConflict = response.results.some(
+    (result) => result.status === 'conflict'
+  );
+  return hasConflict ? 'CONFLICT' : null;
+}
+
+function buildPushResult(args: {
+  outboxCommitId: string;
+  clientCommitId: string;
+  status: PushResultInfo['status'];
+  response: SyncPushResponse;
+}): PushResultInfo {
+  return {
+    outboxCommitId: args.outboxCommitId,
+    clientCommitId: args.clientCommitId,
+    status: args.status,
+    commitSeq: args.response.commitSeq ?? null,
+    results: args.response.results,
+    errorCode: firstPushErrorCode(args.response),
+    timestamp: Date.now(),
+  };
 }
 
 async function syncPushUntilSettled<DB extends SyncClientDb>(
@@ -51,6 +88,7 @@ async function syncPushUntilSettled<DB extends SyncClientDb>(
   const maxCommits = Math.max(1, Math.min(1000, options.maxCommits ?? 20));
 
   let pushedCount = 0;
+  const pushResults: PushResultInfo[] = [];
   for (let i = 0; i < maxCommits; i++) {
     const res = await syncPushOnce(db, transport, {
       clientId: options.clientId,
@@ -59,9 +97,12 @@ async function syncPushUntilSettled<DB extends SyncClientDb>(
     });
     if (!res.pushed) break;
     pushedCount += 1;
+    if (res.pushResult) {
+      pushResults.push(res.pushResult);
+    }
   }
 
-  return { pushedCount };
+  return { pushedCount, pushResults };
 }
 
 interface SyncPullUntilSettledOptions extends SyncPullOnceOptions {
@@ -176,6 +217,7 @@ export interface SyncOnceResult {
   pushedCommits: number;
   pullRounds: number;
   pullResponse: SyncPullResponse;
+  pushResults: PushResultInfo[];
 }
 
 /**
@@ -276,6 +318,7 @@ async function syncOnceCombined<DB extends SyncClientDb>(
 
   // Process push response
   let pushedCommits = 0;
+  const pushResults: PushResultInfo[] = [];
   if (outbox && pushRequest) {
     let pushRes = wsPushResponse ?? combined.push;
     if (!pushRes) {
@@ -303,6 +346,14 @@ async function syncOnceCombined<DB extends SyncClientDb>(
         commitSeq: pushRes.commitSeq ?? null,
         responseJson,
       });
+      pushResults.push(
+        buildPushResult({
+          outboxCommitId: outbox.id,
+          clientCommitId: outbox.client_commit_id,
+          status: pushRes.status,
+          response: pushRes,
+        })
+      );
       pushedCommits = 1;
     } else {
       // Check if all errors are retriable
@@ -317,6 +368,14 @@ async function syncOnceCombined<DB extends SyncClientDb>(
           error: 'Retriable',
           responseJson,
         });
+        pushResults.push(
+          buildPushResult({
+            outboxCommitId: outbox.id,
+            clientCommitId: outbox.client_commit_id,
+            status: 'retriable',
+            response: pushRes,
+          })
+        );
         pushedCommits = 1;
       } else {
         await upsertConflictsForRejectedCommit(db, {
@@ -329,6 +388,14 @@ async function syncOnceCombined<DB extends SyncClientDb>(
           error: 'REJECTED',
           responseJson,
         });
+        pushResults.push(
+          buildPushResult({
+            outboxCommitId: outbox.id,
+            clientCommitId: outbox.client_commit_id,
+            status: 'rejected',
+            response: pushRes,
+          })
+        );
         pushedCommits = 1;
       }
     }
@@ -341,6 +408,7 @@ async function syncOnceCombined<DB extends SyncClientDb>(
       maxCommits: (options.maxPushCommits ?? 20) - 1,
     });
     pushedCommits += remaining.pushedCount;
+    pushResults.push(...remaining.pushResults);
   }
 
   // Process pull response
@@ -376,7 +444,7 @@ async function syncOnceCombined<DB extends SyncClientDb>(
     }
   }
 
-  return { pushedCommits, pullRounds, pullResponse };
+  return { pushedCommits, pullRounds, pullResponse, pushResults };
 }
 
 export async function syncOnce<DB extends SyncClientDb>(