@softure-ai/jobs 0.1.3 → 0.1.4

package/dist/schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,UAAU,gDAAmB,CAAC;AAE3C,eAAO,MAAM,IAAI;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAgBf,CAAC;AAEH,MAAM,MAAM,MAAM,GAAG,OAAO,IAAI,CAAC,YAAY,CAAC;AAE9C,eAAO,MAAM,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAQpB,CAAC"}
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,UAAU,gDAAmB,CAAC;AAE3C,eAAO,MAAM,IAAI;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAgBf,CAAC;AAEH,MAAM,MAAM,MAAM,GAAG,OAAO,IAAI,CAAC,YAAY,CAAC;AAE9C,eAAO,MAAM,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAQpB,CAAC;AAEH,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAKtB,CAAC;AAEH,eAAO,MAAM,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAerB,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG,OAAO,SAAS,CAAC,YAAY,CAAC"}

package/dist/schema.js

@@ -1,6 +1,6 @@
 // Drizzle view of the module's tables (migrations/). The migrations are the source of truth; this
 // file only types the queries.
-import { bigint, integer, jsonb, pgSchema, text, timestamp, uuid } from "drizzle-orm/pg-core";
+import { bigint, integer, jsonb, pgSchema, primaryKey, text, timestamp, uuid } from "drizzle-orm/pg-core";
 export const jobsSchema = pgSchema("jobs");
 export const jobs = jobsSchema.table("jobs", {
     id: bigint("id", { mode: "bigint" }).primaryKey().generatedAlwaysAsIdentity(),
@@ -28,4 +28,22 @@ export const schedules = jobsSchema.table("schedules", {
     createdAt: timestamp("created_at", { withTimezone: true }).notNull(),
     updatedAt: timestamp("updated_at", { withTimezone: true }).notNull(),
 });
+export const syncCursors = jobsSchema.table("sync_cursors", {
+    source: text("source").primaryKey(),
+    cursor: text("cursor").notNull(),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull(),
+    updatedAt: timestamp("updated_at", { withTimezone: true }).notNull(),
+});
+export const syncItems = jobsSchema.table("sync_items", {
+    source: text("source").notNull(),
+    itemId: text("item_id").notNull(),
+    status: text("status", { enum: ["pending", "done", "skipped", "failed"] }).notNull(),
+    errorCode: text("error_code"),
+    attempts: integer("attempts").notNull(),
+    resultRef: text("result_ref"),
+    firstSeenAt: timestamp("first_seen_at", { withTimezone: true }).notNull(),
+    lastSeenAt: timestamp("last_seen_at", { withTimezone: true }).notNull(),
+    updatedAt: timestamp("updated_at", { withTimezone: true }).notNull(),
+    finishedAt: timestamp("finished_at", { withTimezone: true }),
+}, (table) => [primaryKey({ columns: [table.source, table.itemId] })]);
 //# sourceMappingURL=schema.js.map

package/dist/schema.js.map

@@ -1 +1 @@
-{"version":3,"file":"schema.js","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"AAAA,kGAAkG;AAClG,+BAA+B;AAC/B,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,qBAAqB,CAAC;AAE9F,MAAM,CAAC,MAAM,UAAU,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC;AAE3C,MAAM,CAAC,MAAM,IAAI,GAAG,UAAU,CAAC,KAAK,CAAC,MAAM,EAAE;IAC3C,EAAE,EAAE,MAAM,CAAC,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC,CAAC,UAAU,EAAE,CAAC,yBAAyB,EAAE;IAC7E,KAAK,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC,OAAO,EAAE;IAC9B,OAAO,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC,OAAO,EAAE;IACnC,MAAM,EAAE,IAAI,CAAC,QAAQ,EAAE,EAAE,IAAI,EAAE,CAAC,SAAS,EAAE,SAAS,EAAE,WAAW,EAAE,QAAQ,EAAE,WAAW,CAAC,EAAE,CAAC,CAAC,OAAO,EAAE;IACtG,QAAQ,EAAE,OAAO,CAAC,UAAU,CAAC,CAAC,OAAO,EAAE;IACvC,WAAW,EAAE,OAAO,CAAC,cAAc,CAAC,CAAC,OAAO,EAAE;IAC9C,KAAK,EAAE,SAAS,CAAC,QAAQ,EAAE,EAAE,YAAY,EAAE,IAAI,EAAE,CAAC,CAAC,OAAO,EAAE;IAC5D,WAAW,EAAE,SAAS,CAAC,cAAc,EAAE,EAAE,YAAY,EAAE,IAAI,EAAE,CAAC;IAC9D,QAAQ,EAAE,IAAI,CAAC,WAAW,CAAC;IAC3B,UAAU,EAAE,IAAI,CAAC,aAAa,CAAC;IAC/B,QAAQ,EAAE,IAAI,CAAC,WAAW,CAAC;IAC3B,SAAS,EAAE,IAAI,CAAC,YAAY,CAAC;IAC7B,SAAS,EAAE,SAAS,CAAC,YAAY,EAAE,EAAE,YAAY,EAAE,IAAI,EAAE,CAAC,CAAC,OAAO,EAAE;IACpE,SAAS,EAAE,SAAS,CAAC,YAAY,EAAE,EAAE,YAAY,EAAE,IAAI,EAAE,CAAC,CAAC,OAAO,EAAE;IACpE,UAAU,EAAE,SAAS,CAAC,aAAa,EAAE,EAAE,YAAY,EAAE,IAAI,EAAE,CAAC;CAC7D,CAAC,CAAC;AAIH,MAAM,CAAC,MAAM,SAAS,GAAG,UAAU,CAAC,KAAK,CAAC,WAAW,EAAE;IACrD,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC,UAAU,EAAE;IAC/B,UAAU,EAAE,SAAS,CAAC,cAAc,EAAE,EAAE,YAAY,EAAE,IAAI,EAAE,CAAC,CAAC,OAAO,EAAE;IACvE,eAAe,EAAE,SAAS,CAAC,mBAAmB,EAAE,EAAE,YAAY,EAAE,IAAI,EAAE,CAAC;IACvE,YAAY,EAAE,SAAS,CAAC,gBAAgB,EAAE,EAAE,YAAY,EAAE,IAAI,EAAE,CAAC;IACjE,eAAe,EAAE,IAAI,CAAC,mBAAmB,CAAC;IAC1C,SAAS,EAAE,SAAS,CAAC,YAAY,EAAE,EAAE,YAAY,EAAE,IAAI,EAAE,CAAC,CAAC,OAAO,EAAE;IACpE,SAAS,EAAE,SAAS,CAAC,YAAY,EAAE,EAAE,YAAY,EAAE,IAAI,EAAE,CAAC,CAAC,OAAO,EAAE;CACrE,CAAC,CAAC"}
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"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"}

package/dist/server/index.d.ts

@@ -7,5 +7,7 @@ export { getQueueStats, pruneJobs, type QueueStats } from "./maintenance.js";
 export { getJobsOptions } from "./options.js";
 export { runClaimedJob, type RunClaimedJobOptions } from "./process.js";
 export { enqueueDueSchedules, getScheduleSlot, SCHEDULE_DEDUP_KEY, type EnqueueDueSchedulesInput, type ScheduleState, } from "./schedules.js";
+export { advanceSyncCursor, getSyncCursor, SYNC_SOURCE, type AdvanceSyncCursorInput } from "./sync-cursors.js";
+export { listSyncItems, processSyncItem, pruneSyncItems, type ListSyncItemsInput, type ProcessSyncItemInput, type SyncItemContext, } from "./sync-items.js";
 export { runDueJobs, type RunDueJobsOptions, type RunDueJobsReport } from "./run-due.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/server/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,KAAK,eAAe,EAAE,KAAK,cAAc,EAAE,MAAM,YAAY,CAAC;AACpG,OAAO,EACL,SAAS,EACT,WAAW,EACX,cAAc,EACd,UAAU,EACV,KAAK,UAAU,EACf,KAAK,cAAc,EACnB,KAAK,UAAU,GAChB,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,EAAE,UAAU,EAAE,KAAK,WAAW,EAAE,KAAK,eAAe,EAAE,MAAM,cAAc,CAAC;AAClF,OAAO,EAAE,iBAAiB,EAAE,KAAK,aAAa,EAAE,KAAK,UAAU,EAAE,MAAM,aAAa,CAAC;AACrF,OAAO,EAAE,aAAa,EAAE,SAAS,EAAE,KAAK,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC7E,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EAAE,aAAa,EAAE,KAAK,oBAAoB,EAAE,MAAM,cAAc,CAAC;AACxE,OAAO,EACL,mBAAmB,EACnB,eAAe,EACf,kBAAkB,EAClB,KAAK,wBAAwB,EAC7B,KAAK,aAAa,GACnB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,UAAU,EAAE,KAAK,iBAAiB,EAAE,KAAK,gBAAgB,EAAE,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,KAAK,eAAe,EAAE,KAAK,cAAc,EAAE,MAAM,YAAY,CAAC;AACpG,OAAO,EACL,SAAS,EACT,WAAW,EACX,cAAc,EACd,UAAU,EACV,KAAK,UAAU,EACf,KAAK,cAAc,EACnB,KAAK,UAAU,GAChB,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,EAAE,UAAU,EAAE,KAAK,WAAW,EAAE,KAAK,eAAe,EAAE,MAAM,cAAc,CAAC;AAClF,OAAO,EAAE,iBAAiB,EAAE,KAAK,aAAa,EAAE,KAAK,UAAU,EAAE,MAAM,aAAa,CAAC;AACrF,OAAO,EAAE,aAAa,EAAE,SAAS,EAAE,KAAK,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC7E,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EAAE,aAAa,EAAE,KAAK,oBAAoB,EAAE,MAAM,cAAc,CAAC;AACxE,OAAO,EACL,mBAAmB,EACnB,eAAe,EACf,kBAAkB,EAClB,KAAK,wBAAwB,EAC7B,KAAK,aAAa,GACnB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,iBAAiB,EAAE,aAAa,EAAE,WAAW,EAAE,KAAK,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AAC/G,OAAO,EACL,aAAa,EACb,eAAe,EACf,cAAc,EACd,KAAK,kBAAkB,EACvB,KAAK,oBAAoB,EACzB,KAAK,eAAe,GACrB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,UAAU,EAAE,KAAK,iBAAiB,EAAE,KAAK,gBAAgB,EAAE,MAAM,cAAc,CAAC"}

package/dist/server/index.js

@@ -8,5 +8,7 @@ export { getQueueStats, pruneJobs } from "./maintenance.js";
 export { getJobsOptions } from "./options.js";
 export { runClaimedJob } from "./process.js";
 export { enqueueDueSchedules, getScheduleSlot, SCHEDULE_DEDUP_KEY, } from "./schedules.js";
+export { advanceSyncCursor, getSyncCursor, SYNC_SOURCE } from "./sync-cursors.js";
+export { listSyncItems, processSyncItem, pruneSyncItems, } from "./sync-items.js";
 export { runDueJobs } from "./run-due.js";
 //# sourceMappingURL=index.js.map

package/dist/server/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAAA,kHAAkH;AAClH,8BAA8B;AAC9B,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAA6C,MAAM,YAAY,CAAC;AACpG,OAAO,EACL,SAAS,EACT,WAAW,EACX,cAAc,EACd,UAAU,GAIX,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,UAAU,EAA0C,MAAM,cAAc,CAAC;AAClF,OAAO,EAAE,iBAAiB,EAAuC,MAAM,aAAa,CAAC;AACrF,OAAO,EAAE,aAAa,EAAE,SAAS,EAAmB,MAAM,kBAAkB,CAAC;AAC7E,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EAAE,aAAa,EAA6B,MAAM,cAAc,CAAC;AACxE,OAAO,EACL,mBAAmB,EACnB,eAAe,EACf,kBAAkB,GAGnB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,UAAU,EAAiD,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAAA,kHAAkH;AAClH,8BAA8B;AAC9B,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAA6C,MAAM,YAAY,CAAC;AACpG,OAAO,EACL,SAAS,EACT,WAAW,EACX,cAAc,EACd,UAAU,GAIX,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,UAAU,EAA0C,MAAM,cAAc,CAAC;AAClF,OAAO,EAAE,iBAAiB,EAAuC,MAAM,aAAa,CAAC;AACrF,OAAO,EAAE,aAAa,EAAE,SAAS,EAAmB,MAAM,kBAAkB,CAAC;AAC7E,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EAAE,aAAa,EAA6B,MAAM,cAAc,CAAC;AACxE,OAAO,EACL,mBAAmB,EACnB,eAAe,EACf,kBAAkB,GAGnB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,iBAAiB,EAAE,aAAa,EAAE,WAAW,EAA+B,MAAM,mBAAmB,CAAC;AAC/G,OAAO,EACL,aAAa,EACb,eAAe,EACf,cAAc,GAIf,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,UAAU,EAAiD,MAAM,cAAc,CAAC"}

package/dist/server/sync-cursors.d.ts

@@ -0,0 +1,23 @@
+import { type Result } from "@softure-ai/core";
+import type { JobsContext } from "./context.js";
+/** A source name: lowercase letters, digits, `_ . : -`, starting with a letter, up to 127 characters. */
+export declare const SYNC_SOURCE: RegExp;
+export interface AdvanceSyncCursorInput {
+    readonly source: string;
+    /** The cursor the batch was read from, as `getSyncCursor` returned it; null for the first batch. */
+    readonly from: string | null;
+    /** Where the next batch starts. */
+    readonly to: string;
+}
+/** The source's cursor, or null before its first `advanceSyncCursor`. Throws on an invalid source name. */
+export declare function getSyncCursor(ctx: JobsContext, source: string): Promise<string | null>;
+/**
+ * Moves the source's cursor from `from` to `to`, after the batch read from `from` was handled. Refused with
+ * `jobs.sync_cursor_moved` when the stored cursor is no longer `from` (another worker moved it first): re-read from
+ * `getSyncCursor`. `ctx.db` may be a transaction, so the move commits with the batch's last writes. Throws on an
+ * invalid source name or cursor; database failures propagate.
+ */
+export declare function advanceSyncCursor(ctx: JobsContext, input: AdvanceSyncCursorInput): Promise<Result<undefined, "jobs.sync_cursor_moved">>;
+/** Throws on a name the tables refuse: a typo in code, not a user error. */
+export declare function checkSyncSource(source: string): void;
+//# sourceMappingURL=sync-cursors.d.ts.map

package/dist/server/sync-cursors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync-cursors.d.ts","sourceRoot":"","sources":["../../src/server/sync-cursors.ts"],"names":[],"mappings":"AAEA,OAAO,EAAW,KAAK,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAGxD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAEhD,yGAAyG;AACzG,eAAO,MAAM,WAAW,QAA+B,CAAC;AAGxD,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,oGAAoG;IACpG,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,mCAAmC;IACnC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;CACrB;AAED,2GAA2G;AAC3G,wBAAsB,aAAa,CAAC,GAAG,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAI5F;AAED;;;;;GAKG;AACH,wBAAsB,iBAAiB,CAAC,GAAG,EAAE,WAAW,EAAE,KAAK,EAAE,sBAAsB,GAAG,OAAO,CAAC,MAAM,CAAC,SAAS,EAAE,wBAAwB,CAAC,CAAC,CAqB7I;AAED,4EAA4E;AAC5E,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAIpD"}

package/dist/server/sync-cursors.js

@@ -0,0 +1,53 @@
+// The cursor of a polled source: where its next read starts. It moves only by compare-and-set, so a worker that read
+// an older cursor cannot move it back over a newer one; a crash before the move re-reads the batch instead of skipping it.
+import { err, ok } from "@softure-ai/core";
+import { and, eq } from "drizzle-orm";
+import { syncCursors } from "../schema.js";
+/** A source name: lowercase letters, digits, `_ . : -`, starting with a letter, up to 127 characters. */
+export const SYNC_SOURCE = /^[a-z][a-z0-9_.:-]{0,126}$/;
+const MAX_CURSOR_LENGTH = 2000;
+/** The source's cursor, or null before its first `advanceSyncCursor`. Throws on an invalid source name. */
+export async function getSyncCursor(ctx, source) {
+    checkSyncSource(source);
+    const [row] = await ctx.db.select({ cursor: syncCursors.cursor }).from(syncCursors).where(eq(syncCursors.source, source));
+    return row?.cursor ?? null;
+}
+/**
+ * Moves the source's cursor from `from` to `to`, after the batch read from `from` was handled. Refused with
+ * `jobs.sync_cursor_moved` when the stored cursor is no longer `from` (another worker moved it first): re-read from
+ * `getSyncCursor`. `ctx.db` may be a transaction, so the move commits with the batch's last writes. Throws on an
+ * invalid source name or cursor; database failures propagate.
+ */
+export async function advanceSyncCursor(ctx, input) {
+    checkSyncSource(input.source);
+    checkCursor(input.to);
+    if (input.from !== null)
+        checkCursor(input.from);
+    const now = ctx.clock.now();
+    if (input.from === null) {
+        const inserted = await ctx.db
+            .insert(syncCursors)
+            .values({ source: input.source, cursor: input.to, createdAt: now, updatedAt: now })
+            .onConflictDoNothing({ target: syncCursors.source })
+            .returning({ source: syncCursors.source });
+        return inserted.length === 1 ? ok() : err("jobs.sync_cursor_moved");
+    }
+    const updated = await ctx.db
+        .update(syncCursors)
+        .set({ cursor: input.to, updatedAt: now })
+        .where(and(eq(syncCursors.source, input.source), eq(syncCursors.cursor, input.from)))
+        .returning({ source: syncCursors.source });
+    return updated.length === 1 ? ok() : err("jobs.sync_cursor_moved");
+}
+/** Throws on a name the tables refuse: a typo in code, not a user error. */
+export function checkSyncSource(source) {
+    if (!SYNC_SOURCE.test(source)) {
+        throw new RangeError(`@softure-ai/jobs: "${source}" is not a sync source name: lowercase letters, digits, _ . : and -, starting with a letter, up to 127 characters`);
+    }
+}
+function checkCursor(cursor) {
+    if (cursor.length === 0 || cursor.length > MAX_CURSOR_LENGTH) {
+        throw new RangeError(`@softure-ai/jobs: a sync cursor must have 1 to ${String(MAX_CURSOR_LENGTH)} characters`);
+    }
+}
+//# sourceMappingURL=sync-cursors.js.map

package/dist/server/sync-cursors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync-cursors.js","sourceRoot":"","sources":["../../src/server/sync-cursors.ts"],"names":[],"mappings":"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"}

package/dist/server/sync-items.d.ts

@@ -0,0 +1,45 @@
+import { type SyncItemRow } from "../schema.js";
+import type { SyncItem, SyncItemOutcome, SyncItemRunResult, SyncItemStatus } from "../sync.js";
+import type { JobsContext } from "./context.js";
+export interface ProcessSyncItemInput {
+    readonly source: string;
+    /** The item's id at the source. */
+    readonly itemId: string;
+    /** Runs of the callback before the item is `failed` for good; the first run counts. Default 5. */
+    readonly maxAttempts?: number;
+}
+/** What the callback receives: the module context with the item's transaction as `db`, and this attempt's number. */
+export interface SyncItemContext extends JobsContext {
+    /** Starts at 1. */
+    readonly attempt: number;
+}
+export interface ListSyncItemsInput {
+    readonly source?: string;
+    readonly status?: SyncItemStatus;
+    /** Only items whose status, attempts or error changed at or after this time. */
+    readonly since?: Date;
+    /** Default 100, at most 1000. */
+    readonly limit?: number;
+}
+/**
+ * Handles one item of a polled source at most once. Runs `run` unless the ledger already has the item `done`,
+ * `skipped` or `failed` (then `skipped`, the callback untouched). `run` gets the item's transaction as `context.db`:
+ * write the item's effect through it and it commits together with the ledger's `done`. A returned failure rolls those
+ * writes back, counts the attempt and leaves the item `pending` for the next run, or `failed` once `maxAttempts` runs
+ * failed (or at once with `failSyncItem`). A throw is recorded the same way with `jobs.sync_item_threw` and then
+ * rethrown. A call outside the database (an API) is not rolled back: a crash between it and the commit repeats it on
+ * the next run, so keep it idempotent where the source allows. Throws on invalid input; database failures propagate.
+ */
+export declare function processSyncItem(ctx: JobsContext, input: ProcessSyncItemInput, run: (context: SyncItemContext) => Promise<SyncItemRunResult>): Promise<SyncItemOutcome>;
+/**
+ * The ledger, most recently changed first: for an overview page or an MCP tool. Throws on an invalid filter.
+ */
+export declare function listSyncItems(ctx: JobsContext, input?: ListSyncItemsInput): Promise<SyncItem[]>;
+/**
+ * Deletes ledger items that no `processSyncItem` call met for `retention.syncItemsDays`, in batches, whatever their
+ * status: the source no longer returns them. Returns the number deleted. The worker calls it once an hour with
+ * `pruneJobs`; an app without a worker calls it from the same cron.
+ */
+export declare function pruneSyncItems(ctx: JobsContext): Promise<number>;
+export declare function toSyncItem(row: SyncItemRow): SyncItem;
+//# sourceMappingURL=sync-items.d.ts.map

package/dist/server/sync-items.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync-items.d.ts","sourceRoot":"","sources":["../../src/server/sync-items.ts"],"names":[],"mappings":"AAKA,OAAO,EAAa,KAAK,WAAW,EAAE,MAAM,cAAc,CAAC;AAC3D,OAAO,KAAK,EAAE,QAAQ,EAAmB,eAAe,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAChH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAehD,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,mCAAmC;IACnC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,kGAAkG;IAClG,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,qHAAqH;AACrH,MAAM,WAAW,eAAgB,SAAQ,WAAW;IAClD,mBAAmB;IACnB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,CAAC,EAAE,cAAc,CAAC;IACjC,gFAAgF;IAChF,QAAQ,CAAC,KAAK,CAAC,EAAE,IAAI,CAAC;IACtB,iCAAiC;IACjC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAWD;;;;;;;;GAQG;AACH,wBAAsB,eAAe,CACnC,GAAG,EAAE,WAAW,EAChB,KAAK,EAAE,oBAAoB,EAC3B,GAAG,EAAE,CAAC,OAAO,EAAE,eAAe,KAAK,OAAO,CAAC,iBAAiB,CAAC,GAC5D,OAAO,CAAC,eAAe,CAAC,CAsD1B;AAwBD;;GAEG;AACH,wBAAsB,aAAa,CAAC,GAAG,EAAE,WAAW,EAAE,KAAK,GAAE,kBAAuB,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC,CAoBzG;AAED;;;;GAIG;AACH,wBAAsB,cAAc,CAAC,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,CAatE;AAED,wBAAgB,UAAU,CAAC,GAAG,EAAE,WAAW,GAAG,QAAQ,CAarD"}

package/dist/server/sync-items.js

@@ -0,0 +1,195 @@
+import { and, desc, eq, gte, lt, sql } from "drizzle-orm";
+import { syncItems } from "../schema.js";
+import { getJobsOptions } from "./options.js";
+import { checkSyncSource } from "./sync-cursors.js";
+const SYNC_ITEM_THREW = "jobs.sync_item_threw";
+const DEFAULT_MAX_ATTEMPTS = 5;
+const MAX_ITEM_ID_LENGTH = 500;
+const MAX_RESULT_REF_LENGTH = 500;
+const MAX_ERROR_LENGTH = 200;
+const DEFAULT_LIST_LIMIT = 100;
+const MAX_LIST_LIMIT = 1000;
+const DAY_MS = 24 * 60 * 60 * 1000;
+/** Rows deleted per statement, so pruning a large ledger never holds one long lock. */
+const PRUNE_BATCH = 1000;
+/** Thrown inside the savepoint to roll back the callback's writes when it returned a failure. */
+class RunFailed extends Error {
+    result;
+    constructor(result) {
+        super("sync item callback failed");
+        this.result = result;
+    }
+}
+/**
+ * Handles one item of a polled source at most once. Runs `run` unless the ledger already has the item `done`,
+ * `skipped` or `failed` (then `skipped`, the callback untouched). `run` gets the item's transaction as `context.db`:
+ * write the item's effect through it and it commits together with the ledger's `done`. A returned failure rolls those
+ * writes back, counts the attempt and leaves the item `pending` for the next run, or `failed` once `maxAttempts` runs
+ * failed (or at once with `failSyncItem`). A throw is recorded the same way with `jobs.sync_item_threw` and then
+ * rethrown. A call outside the database (an API) is not rolled back: a crash between it and the commit repeats it on
+ * the next run, so keep it idempotent where the source allows. Throws on invalid input; database failures propagate.
+ */
+export async function processSyncItem(ctx, input, run) {
+    checkSyncSource(input.source);
+    const maxAttempts = input.maxAttempts ?? DEFAULT_MAX_ATTEMPTS;
+    checkItemInput(input.itemId, maxAttempts);
+    const now = ctx.clock.now();
+    const settled = await ctx.db.transaction(async (tx) => {
+        const [seen] = await tx
+            .insert(syncItems)
+            .values({ source: input.source, itemId: input.itemId, status: "pending", attempts: 0, firstSeenAt: now, lastSeenAt: now, updatedAt: now })
+            .onConflictDoUpdate({
+            target: [syncItems.source, syncItems.itemId],
+            set: { lastSeenAt: sql `greatest(${syncItems.lastSeenAt}, excluded.last_seen_at)` },
+        })
+            .returning();
+        const row = requireRow(seen);
+        const where = and(eq(syncItems.source, input.source), eq(syncItems.itemId, input.itemId));
+        const finish = async (values) => {
+            const [updated] = await tx.update(syncItems).set({ ...values, updatedAt: now }).where(where).returning();
+            return toSyncItem(requireRow(updated));
+        };
+        if (row.status !== "pending")
+            return { outcome: { kind: "skipped", item: toSyncItem(row) } };
+        if (row.attempts >= maxAttempts) {
+            // maxAttempts was lowered below what the item already used: it has had its runs.
+            const error = row.errorCode ?? SYNC_ITEM_THREW;
+            return { outcome: { kind: "failed", error, item: await finish({ status: "failed", errorCode: error, finishedAt: now }) } };
+        }
+        const attempt = row.attempts + 1;
+        let result;
+        let thrown = null;
+        try {
+            result = await tx.transaction(async (savepoint) => {
+                const returned = await run({ ...ctx, db: savepoint, attempt });
+                if (!isOk(returned))
+                    throw new RunFailed(returned);
+                checkResultRef(returned);
+                return returned;
+            });
+        }
+        catch (error) {
+            if (error instanceof RunFailed) {
+                result = error.result;
+            }
+            else {
+                thrown = { error };
+                result = { ok: false, error: SYNC_ITEM_THREW };
+            }
+        }
+        const outcome = await record(result, { attempt, maxAttempts, now, finish });
+        return thrown === null ? { outcome } : { thrown: thrown.error };
+    });
+    if (settled.outcome === undefined)
+        throw settled.thrown;
+    return settled.outcome;
+}
+async function record(result, context) {
+    const { attempt, now, finish } = context;
+    if (isOk(result)) {
+        const completion = result.value ?? { status: "done" };
+        const item = completion.status === "done"
+            ? await finish({ status: "done", attempts: attempt, errorCode: null, resultRef: completion.resultRef ?? null, finishedAt: now })
+            : await finish({ status: "skipped", attempts: attempt, errorCode: completion.reason === undefined ? null : toErrorCode(completion.reason), finishedAt: now });
+        return { kind: "handled", item };
+    }
+    // A callback that returned neither ok() nor an error (a JavaScript caller) counts as a throw.
+    const failure = result;
+    const error = toErrorCode(typeof failure?.error === "string" ? failure.error : SYNC_ITEM_THREW);
+    if (failure?.retry === false || attempt >= context.maxAttempts) {
+        return { kind: "failed", error, item: await finish({ status: "failed", attempts: attempt, errorCode: error, finishedAt: now }) };
+    }
+    return { kind: "retrying", error, item: await finish({ attempts: attempt, errorCode: error }) };
+}
+/**
+ * The ledger, most recently changed first: for an overview page or an MCP tool. Throws on an invalid filter.
+ */
+export async function listSyncItems(ctx, input = {}) {
+    const limit = input.limit ?? DEFAULT_LIST_LIMIT;
+    if (!(Number.isInteger(limit) && limit >= 1 && limit <= MAX_LIST_LIMIT)) {
+        throw new RangeError(`@softure-ai/jobs: listSyncItems limit must be an integer from 1 to ${String(MAX_LIST_LIMIT)}`);
+    }
+    if (input.source !== undefined)
+        checkSyncSource(input.source);
+    if (input.since !== undefined && Number.isNaN(input.since.getTime())) {
+        throw new RangeError("@softure-ai/jobs: listSyncItems since is an invalid date");
+    }
+    const filters = [];
+    if (input.source !== undefined)
+        filters.push(eq(syncItems.source, input.source));
+    if (input.status !== undefined)
+        filters.push(eq(syncItems.status, input.status));
+    if (input.since !== undefined)
+        filters.push(gte(syncItems.updatedAt, input.since));
+    const rows = await ctx.db
+        .select()
+        .from(syncItems)
+        .where(and(...filters))
+        .orderBy(desc(syncItems.updatedAt), syncItems.source, syncItems.itemId)
+        .limit(limit);
+    return rows.map(toSyncItem);
+}
+/**
+ * Deletes ledger items that no `processSyncItem` call met for `retention.syncItemsDays`, in batches, whatever their
+ * status: the source no longer returns them. Returns the number deleted. The worker calls it once an hour with
+ * `pruneJobs`; an app without a worker calls it from the same cron.
+ */
+export async function pruneSyncItems(ctx) {
+    const { retention } = getJobsOptions(ctx.config);
+    const before = new Date(ctx.clock.now().getTime() - retention.syncItemsDays * DAY_MS);
+    let deleted = 0;
+    for (;;) {
+        const batch = ctx.db.select({ source: syncItems.source, itemId: syncItems.itemId }).from(syncItems).where(lt(syncItems.lastSeenAt, before)).limit(PRUNE_BATCH);
+        const rows = await ctx.db
+            .delete(syncItems)
+            .where(sql `(${syncItems.source}, ${syncItems.itemId}) in (${batch})`)
+            .returning({ source: syncItems.source });
+        deleted += rows.length;
+        if (rows.length < PRUNE_BATCH)
+            return deleted;
+    }
+}
+export function toSyncItem(row) {
+    return {
+        source: row.source,
+        itemId: row.itemId,
+        status: row.status,
+        errorCode: row.errorCode,
+        attempts: row.attempts,
+        resultRef: row.resultRef,
+        firstSeenAt: row.firstSeenAt,
+        lastSeenAt: row.lastSeenAt,
+        updatedAt: row.updatedAt,
+        finishedAt: row.finishedAt,
+    };
+}
+function checkItemInput(itemId, maxAttempts) {
+    if (itemId.length === 0 || itemId.length > MAX_ITEM_ID_LENGTH) {
+        throw new RangeError(`@softure-ai/jobs: a sync item id must have 1 to ${String(MAX_ITEM_ID_LENGTH)} characters`);
+    }
+    if (!(Number.isInteger(maxAttempts) && maxAttempts >= 1 && maxAttempts <= 1000)) {
+        throw new RangeError("@softure-ai/jobs: processSyncItem maxAttempts must be an integer from 1 to 1000");
+    }
+}
+/** Inside the savepoint, so a bad reference counts as a thrown attempt and rolls the callback's writes back. */
+function checkResultRef(result) {
+    const completion = result.ok ? result.value : undefined;
+    if (completion?.status !== "done" || completion.resultRef === undefined)
+        return;
+    if (completion.resultRef.length === 0 || completion.resultRef.length > MAX_RESULT_REF_LENGTH) {
+        throw new RangeError(`@softure-ai/jobs: a sync item resultRef must have 1 to ${String(MAX_RESULT_REF_LENGTH)} characters`);
+    }
+}
+function isOk(result) {
+    return typeof result === "object" && result !== null && result.ok === true;
+}
+function toErrorCode(error) {
+    const trimmed = error.slice(0, MAX_ERROR_LENGTH);
+    return (trimmed.includes(".") ? trimmed : SYNC_ITEM_THREW);
+}
+function requireRow(row) {
+    if (row === undefined)
+        throw new Error("@softure-ai/jobs: a sync item write returned no row");
+    return row;
+}
+//# sourceMappingURL=sync-items.js.map

package/dist/server/sync-items.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync-items.js","sourceRoot":"","sources":["../../src/server/sync-items.ts"],"names":[],"mappings":"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"}

package/dist/sync.d.ts

@@ -0,0 +1,65 @@
+import type { Err, ErrorCode, Ok } from "@softure-ai/core";
+export declare const SYNC_ITEM_STATUSES: readonly ["pending", "done", "skipped", "failed"];
+/** `pending`: seen, not handled yet (a failed attempt with attempts left); `done`, `skipped`, `failed` are final. */
+export type SyncItemStatus = (typeof SYNC_ITEM_STATUSES)[number];
+/** One item of the processed-item ledger. */
+export interface SyncItem {
+    readonly source: string;
+    readonly itemId: string;
+    readonly status: SyncItemStatus;
+    /** The code of the last failed attempt, or why the item was skipped; never a message. */
+    readonly errorCode: string | null;
+    /** Runs of the callback so far. */
+    readonly attempts: number;
+    /** What handling the item produced in the app (a task id), when the callback named it. */
+    readonly resultRef: string | null;
+    readonly firstSeenAt: Date;
+    /** The last time `processSyncItem` met the item; pruning goes by it. */
+    readonly lastSeenAt: Date;
+    /** The last change of status, attempts or error code. */
+    readonly updatedAt: Date;
+    readonly finishedAt: Date | null;
+}
+/** How a callback ends an item well: handled (`ok()`, or `ok({ status: "done", resultRef })`) or deliberately skipped. */
+export type SyncItemCompletion = {
+    readonly status: "done";
+    readonly resultRef?: string;
+} | {
+    readonly status: "skipped";
+    readonly reason?: ErrorCode;
+};
+/** A callback's failure: tried again on the next run unless `retry` is false or the attempts are used up. */
+export type SyncItemFailure = Err<ErrorCode> & {
+    readonly retry?: boolean;
+};
+/** What a `processSyncItem` callback returns. */
+export type SyncItemRunResult = Ok<SyncItemCompletion | undefined> | SyncItemFailure;
+/** What `processSyncItem` did with an item. */
+export type SyncItemOutcome = 
+/** The callback ran and succeeded; `item.status` is `done` or `skipped`. */
+{
+    readonly kind: "handled";
+    readonly item: SyncItem;
+}
+/** The callback failed; the item stays `pending` and the next run tries it again. */
+ | {
+    readonly kind: "retrying";
+    readonly error: string;
+    readonly item: SyncItem;
+}
+/** The callback failed for good (attempts used up, or `failSyncItem`); the item is `failed`. */
+ | {
+    readonly kind: "failed";
+    readonly error: string;
+    readonly item: SyncItem;
+}
+/** The callback did not run: the item was already `done`, `skipped` or `failed` (see `item.status`). */
+ | {
+    readonly kind: "skipped";
+    readonly item: SyncItem;
+};
+/** Ends an item as `skipped` (not relevant to the app), with an optional code saying why; never tried again. */
+export declare function skipSyncItem(reason?: ErrorCode): Ok<SyncItemCompletion>;
+/** A failure that is not retried: the item is `failed` at once with this code. */
+export declare function failSyncItem<E extends ErrorCode>(error: E): SyncItemFailure;
+//# sourceMappingURL=sync.d.ts.map

package/dist/sync.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync.d.ts","sourceRoot":"","sources":["../src/sync.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,GAAG,EAAE,SAAS,EAAE,EAAE,EAAE,MAAM,kBAAkB,CAAC;AAE3D,eAAO,MAAM,kBAAkB,mDAAoD,CAAC;AAEpF,qHAAqH;AACrH,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEjE,6CAA6C;AAC7C,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAChC,yFAAyF;IACzF,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,mCAAmC;IACnC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,0FAA0F;IAC1F,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,QAAQ,CAAC,WAAW,EAAE,IAAI,CAAC;IAC3B,wEAAwE;IACxE,QAAQ,CAAC,UAAU,EAAE,IAAI,CAAC;IAC1B,yDAAyD;IACzD,QAAQ,CAAC,SAAS,EAAE,IAAI,CAAC;IACzB,QAAQ,CAAC,UAAU,EAAE,IAAI,GAAG,IAAI,CAAC;CAClC;AAED,0HAA0H;AAC1H,MAAM,MAAM,kBAAkB,GAC1B;IAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,GACxD;IAAE,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,CAAA;CAAE,CAAC;AAEhE,6GAA6G;AAC7G,MAAM,MAAM,eAAe,GAAG,GAAG,CAAC,SAAS,CAAC,GAAG;IAAE,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC;AAE5E,iDAAiD;AACjD,MAAM,MAAM,iBAAiB,GAAG,EAAE,CAAC,kBAAkB,GAAG,SAAS,CAAC,GAAG,eAAe,CAAC;AAErF,+CAA+C;AAC/C,MAAM,MAAM,eAAe;AACzB,4EAA4E;AAC1E;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;CAAE;AACvD,qFAAqF;GACnF;IAAE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;CAAE;AAChF,gGAAgG;GAC9F;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;CAAE;AAC9E,wGAAwG;GACtG;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;CAAE,CAAC;AAE1D,gHAAgH;AAChH,wBAAgB,YAAY,CAAC,MAAM,CAAC,EAAE,SAAS,GAAG,EAAE,CAAC,kBAAkB,CAAC,CAEvE;AAED,kFAAkF;AAClF,wBAAgB,YAAY,CAAC,CAAC,SAAS,SAAS,EAAE,KAAK,EAAE,CAAC,GAAG,eAAe,CAE3E"}

package/dist/sync.js

@@ -0,0 +1,10 @@
+export const SYNC_ITEM_STATUSES = ["pending", "done", "skipped", "failed"];
+/** Ends an item as `skipped` (not relevant to the app), with an optional code saying why; never tried again. */
+export function skipSyncItem(reason) {
+    return { ok: true, value: reason === undefined ? { status: "skipped" } : { status: "skipped", reason } };
+}
+/** A failure that is not retried: the item is `failed` at once with this code. */
+export function failSyncItem(error) {
+    return { ok: false, error, retry: false };
+}
+//# sourceMappingURL=sync.js.map

package/dist/sync.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync.js","sourceRoot":"","sources":["../src/sync.ts"],"names":[],"mappings":"AAIA,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,QAAQ,CAAU,CAAC;AA8CpF,gHAAgH;AAChH,MAAM,UAAU,YAAY,CAAC,MAAkB;IAC7C,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,EAAE,CAAC;AAC3G,CAAC;AAED,kFAAkF;AAClF,MAAM,UAAU,YAAY,CAAsB,KAAQ;IACxD,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;AAC5C,CAAC"}

package/dist/testing/index.d.ts

@@ -1,6 +1,15 @@
 import type { Queryable } from "@softure-ai/db";
 import type { Job } from "../contract.js";
+import type { SyncItem } from "../sync.js";
 export { runDueJobs, type RunDueJobsOptions, type RunDueJobsReport } from "../server/run-due.js";
 /** Every job in the table, oldest first: for assertions. */
 export declare function listJobs(db: Queryable): Promise<Job[]>;
+export interface SyncState {
+    /** Every source's cursor, by source name. */
+    readonly cursors: Readonly<Record<string, string>>;
+    /** Every ledger item, by source and then item id. */
+    readonly items: SyncItem[];
+}
+/** The whole sync state, cursors and ledger: for assertions after a test ran its polling job (`runDueJobs`). */
+export declare function listSyncState(db: Queryable): Promise<SyncState>;
 //# sourceMappingURL=index.d.ts.map

package/dist/testing/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/testing/index.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAEhD,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,gBAAgB,CAAC;AAI1C,OAAO,EAAE,UAAU,EAAE,KAAK,iBAAiB,EAAE,KAAK,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAEjG,4DAA4D;AAC5D,wBAAsB,QAAQ,CAAC,EAAE,EAAE,SAAS,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC,CAG5D"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/testing/index.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAEhD,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,gBAAgB,CAAC;AAI1C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE3C,OAAO,EAAE,UAAU,EAAE,KAAK,iBAAiB,EAAE,KAAK,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAEjG,4DAA4D;AAC5D,wBAAsB,QAAQ,CAAC,EAAE,EAAE,SAAS,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC,CAG5D;AAED,MAAM,WAAW,SAAS;IACxB,6CAA6C;IAC7C,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACnD,qDAAqD;IACrD,QAAQ,CAAC,KAAK,EAAE,QAAQ,EAAE,CAAC;CAC5B;AAED,gHAAgH;AAChH,wBAAsB,aAAa,CAAC,EAAE,EAAE,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC,CAIrE"}

package/dist/testing/index.js

@@ -1,10 +1,17 @@
 import { asc } from "drizzle-orm";
-import { jobs } from "../schema.js";
+import { jobs, syncCursors, syncItems } from "../schema.js";
 import { toJob } from "../server/job-row.js";
+import { toSyncItem } from "../server/sync-items.js";
 export { runDueJobs } from "../server/run-due.js";
 /** Every job in the table, oldest first: for assertions. */
 export async function listJobs(db) {
     const rows = await db.select().from(jobs).orderBy(asc(jobs.id));
     return rows.map(toJob);
 }
+/** The whole sync state, cursors and ledger: for assertions after a test ran its polling job (`runDueJobs`). */
+export async function listSyncState(db) {
+    const cursors = await db.select().from(syncCursors).orderBy(asc(syncCursors.source));
+    const items = await db.select().from(syncItems).orderBy(asc(syncItems.source), asc(syncItems.itemId));
+    return { cursors: Object.fromEntries(cursors.map((row) => [row.source, row.cursor])), items: items.map(toSyncItem) };
+}
 //# sourceMappingURL=index.js.map

package/dist/testing/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/testing/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,GAAG,EAAE,MAAM,aAAa,CAAC;AAElC,OAAO,EAAE,IAAI,EAAE,MAAM,cAAc,CAAC;AACpC,OAAO,EAAE,KAAK,EAAE,MAAM,sBAAsB,CAAC;AAE7C,OAAO,EAAE,UAAU,EAAiD,MAAM,sBAAsB,CAAC;AAEjG,4DAA4D;AAC5D,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,EAAa;IAC1C,MAAM,IAAI,GAAG,MAAM,EAAE,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC;IAChE,OAAO,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;AACzB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/testing/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,GAAG,EAAE,MAAM,aAAa,CAAC;AAElC,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAC5D,OAAO,EAAE,KAAK,EAAE,MAAM,sBAAsB,CAAC;AAC7C,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAGrD,OAAO,EAAE,UAAU,EAAiD,MAAM,sBAAsB,CAAC;AAEjG,4DAA4D;AAC5D,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,EAAa;IAC1C,MAAM,IAAI,GAAG,MAAM,EAAE,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC;IAChE,OAAO,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;AACzB,CAAC;AASD,gHAAgH;AAChH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,EAAa;IAC/C,MAAM,OAAO,GAAG,MAAM,EAAE,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC;IACrF,MAAM,KAAK,GAAG,MAAM,EAAE,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,GAAG,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC;IACtG,OAAO,EAAE,OAAO,EAAE,MAAM,CAAC,WAAW,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,UAAU,CAAC,EAAE,CAAC;AACvH,CAAC"}

package/dist/worker/run-job-worker.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"run-job-worker.d.ts","sourceRoot":"","sources":["../../src/worker/run-job-worker.ts"],"names":[],"mappings":"AAIA,OAAO,EAAe,KAAK,KAAK,EAAE,KAAK,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAC/E,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAIlD,OAAO,EAAqB,KAAK,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAWzE,MAAM,WAAW,mBAAmB;IAClC,oHAAoH;IACpH,QAAQ,CAAC,EAAE,EAAE,SAAS,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC;IAC/B,gGAAgG;IAChG,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,wEAAwE;IACxE,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,QAAQ,CAAC,MAAM,CAAC,EAAE,UAAU,CAAC;IAC7B,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC;IACvB,yDAAyD;IACzD,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,6CAA6C;IAC7C,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,MAAM,CAAC;IAC/B,kGAAkG;IAClG,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B;;;OAGG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAQD;;;;GAIG;AACH,wBAAsB,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,CAiG9E"}
+{"version":3,"file":"run-job-worker.d.ts","sourceRoot":"","sources":["../../src/worker/run-job-worker.ts"],"names":[],"mappings":"AAIA,OAAO,EAAe,KAAK,KAAK,EAAE,KAAK,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAC/E,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAIlD,OAAO,EAAqB,KAAK,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAYzE,MAAM,WAAW,mBAAmB;IAClC,oHAAoH;IACpH,QAAQ,CAAC,EAAE,EAAE,SAAS,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC;IAC/B,gGAAgG;IAChG,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,wEAAwE;IACxE,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,QAAQ,CAAC,MAAM,CAAC,EAAE,UAAU,CAAC;IAC7B,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC;IACvB,yDAAyD;IACzD,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,6CAA6C;IAC7C,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,MAAM,CAAC;IAC/B,kGAAkG;IAClG,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B;;;OAGG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAQD;;;;GAIG;AACH,wBAAsB,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,CAuG9E"}

package/dist/worker/run-job-worker.js

@@ -7,6 +7,7 @@ import { claimJobs, extendJobLease, releaseJob } from "../server/claim.js";
 import { checkHandlers } from "../server/handler-check.js";
 import { consoleJobsLogger } from "../server/logger.js";
 import { pruneJobs } from "../server/maintenance.js";
+import { pruneSyncItems } from "../server/sync-items.js";
 import { getJobsOptions, getQueue } from "../server/options.js";
 import { runClaimedJob } from "../server/process.js";
 import { enqueueScheduledRun, getSchedule, getScheduleNames, getScheduleSlot } from "../server/schedules.js";
@@ -108,6 +109,14 @@ export async function runJobWorker(options) {
             catch (error) {
                 logger.error("could not prune finished jobs", { error });
             }
+            try {
+                const deleted = await pruneSyncItems(ctx);
+                if (deleted > 0)
+                    logger.info("pruned sync ledger items", { deleted });
+            }
+            catch (error) {
+                logger.error("could not prune sync ledger items", { error });
+            }
         }
         if (!isClaimFailed)
             healthFile?.touch();