npm install @systemoperator/sync

import { withSyncRun } from '@systemoperator/sync';
const result = await withSyncRun(
  {
    step,                    // Cloudflare WorkflowStep
    tracker: mySyncTracker,  // implements SyncRunTracker
    config: { runType: 'sync_stripe', caller: 'stripe-sync' },
    payload: { connectionId: 'conn-1', trigger: 'cron' },
    lockStore: myLockStore,  // optional, implements SyncLockStore
    notifier: myNotifier,    // optional, implements SyncNotifier
  },
  async (ctx) => {
    // ctx has: runId, counts, checkTimeout(), payload, config
    await paginateCursor(step, ctx, { ... });
  },
);

import { paginateCursor, paginateOffset } from '@systemoperator/sync';
await paginateCursor(step, ctx, {
  stepPrefix: 'charges',
  fetchPage: async (cursor) => stripe.charges.list({ starting_after: cursor }),
  processPage: async (items) => processCharges(items),
  getCursor: (items) => items.at(-1)!.id,
});
await paginateOffset(step, ctx, {
  stepPrefix: 'transactions',
  limit: 100,
  fetchPage: async (offset, limit) => mercury.listTransactions({ offset, limit }),
  processPage: async (items) => processTransactions(items),
});

import { computeContentHash, upsertWithHash, determineAction } from '@systemoperator/sync';
const hash = await computeContentHash(apiRecord);
const result = await upsertWithHash({
  newHash: hash,
  insert: () => db.insert(charges).values({ ...data, contentHash: hash }),
  findExisting: () => db.select().from(charges).where(eq(charges.externalId, id)),
  update: (existingId) => db.update(charges).set({ ...data, contentHash: hash }).where(eq(charges.id, existingId)),
});
// result: 'created' | 'updated' | 'unchanged'

import { withRetry, RETRY_PRESETS, RetryableError } from '@systemoperator/sync';
const data = await withRetry(step, 'fetch-charges', async () => {
  const res = await fetch(url);
  if (!res.ok) throw new RetryableError(`HTTP ${res.status}`);
  return res.json();
}, RETRY_PRESETS.standard);

import { processBatchWithTimeout } from '@systemoperator/sync';
const allDone = await processBatchWithTimeout(step, items, {
  batchSize: 50,
  checkTimeout: ctx.checkTimeout,
  processItem: async (item) => processOne(item),
  counts: ctx.counts,
});

import type { SyncRunTracker, SyncLockStore, SyncNotifier } from '@systemoperator/sync';
const tracker: SyncRunTracker = {
  async createAndStartRun(runType, trigger, input) { /* create run record, return ID */ },
  async finishRun(runId, output) { /* mark run completed */ },
  async failRun(runId, error, output) { /* mark run failed */ },
};
const lockStore: SyncLockStore = {
  async acquireLock(resourceId, lockOwner, timeoutMs) { /* pessimistic lock */ },
  async releaseLock(resourceId) { /* release lock */ },
};