clivly 0.12.0 → 0.14.1

package/{sdk-C-Pjxj2y.mjs → sdk-DLoVPlGB.mjs}

@@ -699,6 +699,20 @@ function detectHostEnvironment(env, configured) {
 	return fromNodeEnv(env.NODE_ENV?.trim());
 }
 //#endregion
+//#region ../sdk/src/instant-push-support.ts
+/**
+* The fast rollback switch for instant push (see
+* docs/reviews/2026-09-19-near-real-time-sync-plan.md, question 5).
+*
+* A host-side env var, not a Clivly-Cloud-side toggle: it must keep working
+* even when Clivly Cloud is the thing misbehaving (e.g. its ingest endpoint
+* is what instant push is flooding), and it must take effect without a
+* redeploy — just an env var change and the next cold start.
+*/
+function isInstantPushDisabled(env) {
+	return env.CLIVLY_INSTANT_PUSH_DISABLED === "true";
+}
+//#endregion
 //#region ../sdk/src/presence-machine.ts
 const PRESENCE_BACKOFF_BASE_MS = 1e3;
 const PRESENCE_BACKOFF_MAX_MS = 3e4;
@@ -1377,6 +1391,51 @@ async function fullSyncSource(args) {
 	};
 }
 //#endregion
+//#region ../sdk/src/trigger-method.ts
+/** Host-side override, mirroring `CLIVLY_INSTANT_PUSH_DISABLED`. */
+const REQUIRE_POST_ENV_VAR = "CLIVLY_TRIGGER_REQUIRE_POST";
+const NON_POST_DEPRECATION_WARNING = `Clivly: this sync trigger was called with GET. It still ran the sync, but a future release will refuse any method except POST with a 405. Change the caller — your cron job or uptime check — to POST. To adopt the new behaviour now, set ${REQUIRE_POST_ENV_VAR}=true.`;
+const METHOD_NOT_ALLOWED = 405;
+const NO_CONTENT = 204;
+const OK = 200;
+/**
+* Resolve the phase. Only the exact strings `"true"` and `"false"` count —
+* anything else (unset, empty, `"1"`, `"TRUE"`) falls through to the default
+* rather than guessing, so a typo can never silently disable a guard.
+*/
+function enforcementEnabled(input) {
+	const override = input.env[REQUIRE_POST_ENV_VAR];
+	if (override === "true") return true;
+	if (override === "false") return false;
+	return input.enforceDefault;
+}
+function resolveTriggerMethod(input) {
+	const method = input.method.toUpperCase();
+	if (method === "POST") return {
+		runSync: true,
+		status: OK
+	};
+	if (method === "HEAD") return {
+		runSync: false,
+		status: NO_CONTENT
+	};
+	const refuse = {
+		body: {
+			error: `Method ${method} is not allowed on the Clivly sync trigger. Use POST.`,
+			ok: false
+		},
+		runSync: false,
+		status: METHOD_NOT_ALLOWED
+	};
+	if (method !== "GET") return refuse;
+	if (enforcementEnabled(input)) return refuse;
+	return {
+		runSync: true,
+		status: OK,
+		warn: NON_POST_DEPRECATION_WARNING
+	};
+}
+//#endregion
 //#region ../sdk/src/trigger-url.ts
 const SCHEME_REGEX = /^https?:\/\//;
 const INVALID_HOST_CHARS_REGEX = /[/\\@?#\s]/;
@@ -1688,7 +1747,7 @@ function buildSchema(config) {
 	});
 }
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
-function createMemoryCursorStore() {
+function memoryCursorStore() {
 	const cursors = /* @__PURE__ */ new Map();
 	return {
 		get: (entity) => cursors.get(entity) ?? null,
@@ -1697,6 +1756,56 @@ function createMemoryCursorStore() {
 		}
 	};
 }
+/** Default key prefix for {@link kvCursorStore}. */
+const CURSOR_KEY_PREFIX = "clivly:cursor:";
+/**
+* A persistent `CursorStore` backed by any key-value store.
+*
+* Serverless runtimes discard memory between invocations, so without a
+* persisted cursor every `delta` sync starts from `null` and re-reads the
+* whole source table. That is invisible — the run succeeds — and bills like a
+* full sync forever.
+*
+* This exists because the hand-written version has a trap in it:
+* `SyncCursor.time` is a `Date`, which a JSON round-trip turns into a string,
+* and `fromDrizzle` then calls `since.time.toISOString()` on it. The cursor is
+* stored as an ISO string and parsed back to a `Date` here so no caller has to
+* remember that.
+*
+* ```ts
+* cursorStore: kvCursorStore(env.CLIVLY_CURSORS) // Workers KV binding
+* ```
+*
+* A malformed or partial stored value resolves to `null` rather than throwing:
+* the worst case is one full re-read, where throwing would wedge sync entirely.
+*/
+function kvCursorStore(kv, options) {
+	const prefix = options?.prefix ?? "clivly:cursor:";
+	const keyFor = (entity) => `${prefix}${entity}`;
+	return {
+		get: async (entity) => {
+			const raw = await kv.get(keyFor(entity));
+			if (!raw) return null;
+			try {
+				const parsed = JSON.parse(raw);
+				if (typeof parsed.id !== "string" || typeof parsed.time !== "string") return null;
+				const time = new Date(parsed.time);
+				return Number.isNaN(time.getTime()) ? null : {
+					id: parsed.id,
+					time
+				};
+			} catch {
+				return null;
+			}
+		},
+		set: async (entity, cursor) => {
+			await kv.put(keyFor(entity), cursor === null ? "" : JSON.stringify({
+				id: cursor.id,
+				time: cursor.time.toISOString()
+			}));
+		}
+	};
+}
 function isLikelyServerless() {
 	const runtime = globalThis;
 	if (runtime.navigator?.userAgent === "Cloudflare-Workers") return true;
@@ -1926,9 +2035,11 @@ function createClivlySDK(config) {
 	let presenceClient = null;
 	let httpHeartbeatActive = true;
 	const batchSize = config.sync?.batchSize ?? DEFAULT_BATCH_SIZE;
-	const cursorStore = config.cursorStore ?? createMemoryCursorStore();
+	if (serverless && !config.cursorStore) console.warn("Clivly: no `cursorStore` is configured and this looks like a serverless/edge runtime, where memory does not survive between invocations. Every `delta` sync will start from scratch and re-read your entire source tables — a full sync, on every run, billed as such. Pass a persistent store: `cursorStore: kvCursorStore(env.MY_KV)` (exported from `@clivly/sdk`). See https://clivly.com/docs/concepts/sync#cursor-stores");
+	const cursorStore = config.cursorStore ?? memoryCursorStore();
 	const fetcher = createFetcher(config.retry);
 	let warnedUnsignedTrigger = false;
+	let warnedNonPostTrigger = false;
 	const remoteProjections = createRemoteProjectionFetcher({
 		apiKey: config.apiKey,
 		apiUrl,
@@ -2090,6 +2201,28 @@ function createClivlySDK(config) {
 		lastPushFailure = null;
 		if (!await syncOne(resolved.source, resolved.path, "delta", resolved.objectType, runId, SAMPLE_BATCH_SIZE, SAMPLE_BATCH_SIZE, false)) throw pushFailureError(describePushFailure([resolved.source.entity]));
 	};
+	const pushOne = async (entityKey, row) => {
+		if (config.sync?.instant !== true) return;
+		if (isInstantPushDisabled(config.env ?? process.env)) return;
+		const resolved = resolveEntitySource(config, entityKey);
+		if (!resolved) {
+			console.warn(`Clivly instant push: no source is configured for entity "${entityKey}" — this row was not pushed. It will still sync on the next delta run once \`entities\` declares it.`);
+			return;
+		}
+		const path = CONCEPT_PATHS[resolved.expectedKey];
+		if (!path) return;
+		const push = createPush();
+		try {
+			if (!await push(path, {
+				source: pushSourceOf(resolved.source),
+				rows: [row],
+				mode: "delta",
+				...resolved.expectedKey === "custom" ? { objectType: resolved.source.objectType } : {}
+			})) console.warn(`Clivly instant push failed for "${entityKey}". This row will still sync on the next delta run.`);
+		} catch (error) {
+			console.warn(`Clivly instant push failed for "${entityKey}": ${error instanceof Error ? error.message : String(error)}. This row will still sync on the next delta run.`);
+		}
+	};
 	const describeSyncTrigger = () => ({
 		configured: config.syncTrigger?.url,
 		resolved: resolveTriggerUrl({
@@ -2332,8 +2465,45 @@ function createClivlySDK(config) {
 			return {};
 		}
 	};
+	/**
+	* The response to send instead of running a sync, or null to proceed.
+	*
+	* Split out of the handler so the method decision reads as one thing rather
+	* than three branches ahead of the request plumbing — the same shape as
+	* `triggerRequestAllowed` below.
+	*/
+	const refuseDisallowedMethod = (req) => {
+		const decision = resolveTriggerMethod({
+			enforceDefault: false,
+			env: config.env ?? process.env,
+			method: req.method
+		});
+		if (decision.warn && !warnedNonPostTrigger) {
+			warnedNonPostTrigger = true;
+			console.warn(decision.warn);
+		}
+		if (decision.runSync) return null;
+		return decision.body ? jsonResponse(decision.body, decision.status) : new Response(null, { status: decision.status });
+	};
+	/**
+	* Serve a preview request, or null when this payload is a real sync.
+	*
+	* Preview (T10) is a signed, ZERO-WRITE dry run: it returns ≤5 RAW source
+	* rows, slimmed to only the columns the draft maps or filters on and coerced
+	* to JSON scalars, which the cloud then projects through the same path as a
+	* real sync. It never syncs, never pushes, never writes a cursor and never
+	* ingests. Callers keep it inside their `try` so a malformed body or a
+	* throwing `fetchPage` degrades to the same graceful 500 as the sync paths.
+	*/
+	const handleIfPreview = async (payload) => {
+		if (payload.preview) return await handlePreviewRequest(config, payload.preview);
+		if (payload.previewProjection) return await handleProjectionPreviewRequest(config, payload.previewProjection);
+		return null;
+	};
 	const createClivlyHandler = () => async (req) => {
 		observedUrl = observedTriggerUrl(req) ?? observedUrl;
+		const refusal = refuseDisallowedMethod(req);
+		if (refusal) return refusal;
 		const rawBody = await req.text().catch(() => "");
 		if (!await triggerRequestAllowed(req, rawBody)) return jsonResponse({
 			ok: false,
@@ -2343,8 +2513,8 @@ function createClivlySDK(config) {
 		const runId = payload.runId ?? null;
 		const startedAt = Date.now();
 		try {
-			if (payload.preview) return await handlePreviewRequest(config, payload.preview);
-			if (payload.previewProjection) return await handleProjectionPreviewRequest(config, payload.previewProjection);
+			const previewResponse = await handleIfPreview(payload);
+			if (previewResponse) return previewResponse;
 			if (payload.sample) await runSampleSync(payload.sample.entityKey, payload.runId);
 			else await runScheduled({
 				mode: payload.mode,
@@ -2445,8 +2615,9 @@ function createClivlySDK(config) {
 		runScheduled,
 		createClivlyHandler,
 		sync: runSync,
-		createAuthVerifyHandler
+		createAuthVerifyHandler,
+		pushOne
 	};
 }
 //#endregion
-export { ClivlyRateLimitError as a, ClivlyNetworkError as i, ClivlyAuthError as n, createChatSessionHandler as o, ClivlyError as r, isPlaceholderUrl as s, createClivlySDK as t };
+export { ClivlyAuthError as a, ClivlyRateLimitError as c, memoryCursorStore as i, createChatSessionHandler as l, createClivlySDK as n, ClivlyError as o, kvCursorStore as r, ClivlyNetworkError as s, CURSOR_KEY_PREFIX as t, isPlaceholderUrl as u };

package/{sdk-BvGSxBQc.cjs → sdk-ZMy4C4VK.cjs}

@@ -699,6 +699,20 @@ function detectHostEnvironment(env, configured) {
 	return fromNodeEnv(env.NODE_ENV?.trim());
 }
 //#endregion
+//#region ../sdk/src/instant-push-support.ts
+/**
+* The fast rollback switch for instant push (see
+* docs/reviews/2026-09-19-near-real-time-sync-plan.md, question 5).
+*
+* A host-side env var, not a Clivly-Cloud-side toggle: it must keep working
+* even when Clivly Cloud is the thing misbehaving (e.g. its ingest endpoint
+* is what instant push is flooding), and it must take effect without a
+* redeploy — just an env var change and the next cold start.
+*/
+function isInstantPushDisabled(env) {
+	return env.CLIVLY_INSTANT_PUSH_DISABLED === "true";
+}
+//#endregion
 //#region ../sdk/src/presence-machine.ts
 const PRESENCE_BACKOFF_BASE_MS = 1e3;
 const PRESENCE_BACKOFF_MAX_MS = 3e4;
@@ -1377,6 +1391,51 @@ async function fullSyncSource(args) {
 	};
 }
 //#endregion
+//#region ../sdk/src/trigger-method.ts
+/** Host-side override, mirroring `CLIVLY_INSTANT_PUSH_DISABLED`. */
+const REQUIRE_POST_ENV_VAR = "CLIVLY_TRIGGER_REQUIRE_POST";
+const NON_POST_DEPRECATION_WARNING = `Clivly: this sync trigger was called with GET. It still ran the sync, but a future release will refuse any method except POST with a 405. Change the caller — your cron job or uptime check — to POST. To adopt the new behaviour now, set ${REQUIRE_POST_ENV_VAR}=true.`;
+const METHOD_NOT_ALLOWED = 405;
+const NO_CONTENT = 204;
+const OK = 200;
+/**
+* Resolve the phase. Only the exact strings `"true"` and `"false"` count —
+* anything else (unset, empty, `"1"`, `"TRUE"`) falls through to the default
+* rather than guessing, so a typo can never silently disable a guard.
+*/
+function enforcementEnabled(input) {
+	const override = input.env[REQUIRE_POST_ENV_VAR];
+	if (override === "true") return true;
+	if (override === "false") return false;
+	return input.enforceDefault;
+}
+function resolveTriggerMethod(input) {
+	const method = input.method.toUpperCase();
+	if (method === "POST") return {
+		runSync: true,
+		status: OK
+	};
+	if (method === "HEAD") return {
+		runSync: false,
+		status: NO_CONTENT
+	};
+	const refuse = {
+		body: {
+			error: `Method ${method} is not allowed on the Clivly sync trigger. Use POST.`,
+			ok: false
+		},
+		runSync: false,
+		status: METHOD_NOT_ALLOWED
+	};
+	if (method !== "GET") return refuse;
+	if (enforcementEnabled(input)) return refuse;
+	return {
+		runSync: true,
+		status: OK,
+		warn: NON_POST_DEPRECATION_WARNING
+	};
+}
+//#endregion
 //#region ../sdk/src/trigger-url.ts
 const SCHEME_REGEX = /^https?:\/\//;
 const INVALID_HOST_CHARS_REGEX = /[/\\@?#\s]/;
@@ -1688,7 +1747,7 @@ function buildSchema(config) {
 	});
 }
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
-function createMemoryCursorStore() {
+function memoryCursorStore() {
 	const cursors = /* @__PURE__ */ new Map();
 	return {
 		get: (entity) => cursors.get(entity) ?? null,
@@ -1697,6 +1756,56 @@ function createMemoryCursorStore() {
 		}
 	};
 }
+/** Default key prefix for {@link kvCursorStore}. */
+const CURSOR_KEY_PREFIX = "clivly:cursor:";
+/**
+* A persistent `CursorStore` backed by any key-value store.
+*
+* Serverless runtimes discard memory between invocations, so without a
+* persisted cursor every `delta` sync starts from `null` and re-reads the
+* whole source table. That is invisible — the run succeeds — and bills like a
+* full sync forever.
+*
+* This exists because the hand-written version has a trap in it:
+* `SyncCursor.time` is a `Date`, which a JSON round-trip turns into a string,
+* and `fromDrizzle` then calls `since.time.toISOString()` on it. The cursor is
+* stored as an ISO string and parsed back to a `Date` here so no caller has to
+* remember that.
+*
+* ```ts
+* cursorStore: kvCursorStore(env.CLIVLY_CURSORS) // Workers KV binding
+* ```
+*
+* A malformed or partial stored value resolves to `null` rather than throwing:
+* the worst case is one full re-read, where throwing would wedge sync entirely.
+*/
+function kvCursorStore(kv, options) {
+	const prefix = options?.prefix ?? "clivly:cursor:";
+	const keyFor = (entity) => `${prefix}${entity}`;
+	return {
+		get: async (entity) => {
+			const raw = await kv.get(keyFor(entity));
+			if (!raw) return null;
+			try {
+				const parsed = JSON.parse(raw);
+				if (typeof parsed.id !== "string" || typeof parsed.time !== "string") return null;
+				const time = new Date(parsed.time);
+				return Number.isNaN(time.getTime()) ? null : {
+					id: parsed.id,
+					time
+				};
+			} catch {
+				return null;
+			}
+		},
+		set: async (entity, cursor) => {
+			await kv.put(keyFor(entity), cursor === null ? "" : JSON.stringify({
+				id: cursor.id,
+				time: cursor.time.toISOString()
+			}));
+		}
+	};
+}
 function isLikelyServerless() {
 	const runtime = globalThis;
 	if (runtime.navigator?.userAgent === "Cloudflare-Workers") return true;
@@ -1926,9 +2035,11 @@ function createClivlySDK(config) {
 	let presenceClient = null;
 	let httpHeartbeatActive = true;
 	const batchSize = config.sync?.batchSize ?? DEFAULT_BATCH_SIZE;
-	const cursorStore = config.cursorStore ?? createMemoryCursorStore();
+	if (serverless && !config.cursorStore) console.warn("Clivly: no `cursorStore` is configured and this looks like a serverless/edge runtime, where memory does not survive between invocations. Every `delta` sync will start from scratch and re-read your entire source tables — a full sync, on every run, billed as such. Pass a persistent store: `cursorStore: kvCursorStore(env.MY_KV)` (exported from `@clivly/sdk`). See https://clivly.com/docs/concepts/sync#cursor-stores");
+	const cursorStore = config.cursorStore ?? memoryCursorStore();
 	const fetcher = createFetcher(config.retry);
 	let warnedUnsignedTrigger = false;
+	let warnedNonPostTrigger = false;
 	const remoteProjections = createRemoteProjectionFetcher({
 		apiKey: config.apiKey,
 		apiUrl,
@@ -2090,6 +2201,28 @@ function createClivlySDK(config) {
 		lastPushFailure = null;
 		if (!await syncOne(resolved.source, resolved.path, "delta", resolved.objectType, runId, SAMPLE_BATCH_SIZE, SAMPLE_BATCH_SIZE, false)) throw pushFailureError(describePushFailure([resolved.source.entity]));
 	};
+	const pushOne = async (entityKey, row) => {
+		if (config.sync?.instant !== true) return;
+		if (isInstantPushDisabled(config.env ?? process.env)) return;
+		const resolved = resolveEntitySource(config, entityKey);
+		if (!resolved) {
+			console.warn(`Clivly instant push: no source is configured for entity "${entityKey}" — this row was not pushed. It will still sync on the next delta run once \`entities\` declares it.`);
+			return;
+		}
+		const path = CONCEPT_PATHS[resolved.expectedKey];
+		if (!path) return;
+		const push = createPush();
+		try {
+			if (!await push(path, {
+				source: pushSourceOf(resolved.source),
+				rows: [row],
+				mode: "delta",
+				...resolved.expectedKey === "custom" ? { objectType: resolved.source.objectType } : {}
+			})) console.warn(`Clivly instant push failed for "${entityKey}". This row will still sync on the next delta run.`);
+		} catch (error) {
+			console.warn(`Clivly instant push failed for "${entityKey}": ${error instanceof Error ? error.message : String(error)}. This row will still sync on the next delta run.`);
+		}
+	};
 	const describeSyncTrigger = () => ({
 		configured: config.syncTrigger?.url,
 		resolved: resolveTriggerUrl({
@@ -2332,8 +2465,45 @@ function createClivlySDK(config) {
 			return {};
 		}
 	};
+	/**
+	* The response to send instead of running a sync, or null to proceed.
+	*
+	* Split out of the handler so the method decision reads as one thing rather
+	* than three branches ahead of the request plumbing — the same shape as
+	* `triggerRequestAllowed` below.
+	*/
+	const refuseDisallowedMethod = (req) => {
+		const decision = resolveTriggerMethod({
+			enforceDefault: false,
+			env: config.env ?? process.env,
+			method: req.method
+		});
+		if (decision.warn && !warnedNonPostTrigger) {
+			warnedNonPostTrigger = true;
+			console.warn(decision.warn);
+		}
+		if (decision.runSync) return null;
+		return decision.body ? jsonResponse(decision.body, decision.status) : new Response(null, { status: decision.status });
+	};
+	/**
+	* Serve a preview request, or null when this payload is a real sync.
+	*
+	* Preview (T10) is a signed, ZERO-WRITE dry run: it returns ≤5 RAW source
+	* rows, slimmed to only the columns the draft maps or filters on and coerced
+	* to JSON scalars, which the cloud then projects through the same path as a
+	* real sync. It never syncs, never pushes, never writes a cursor and never
+	* ingests. Callers keep it inside their `try` so a malformed body or a
+	* throwing `fetchPage` degrades to the same graceful 500 as the sync paths.
+	*/
+	const handleIfPreview = async (payload) => {
+		if (payload.preview) return await handlePreviewRequest(config, payload.preview);
+		if (payload.previewProjection) return await handleProjectionPreviewRequest(config, payload.previewProjection);
+		return null;
+	};
 	const createClivlyHandler = () => async (req) => {
 		observedUrl = observedTriggerUrl(req) ?? observedUrl;
+		const refusal = refuseDisallowedMethod(req);
+		if (refusal) return refusal;
 		const rawBody = await req.text().catch(() => "");
 		if (!await triggerRequestAllowed(req, rawBody)) return jsonResponse({
 			ok: false,
@@ -2343,8 +2513,8 @@ function createClivlySDK(config) {
 		const runId = payload.runId ?? null;
 		const startedAt = Date.now();
 		try {
-			if (payload.preview) return await handlePreviewRequest(config, payload.preview);
-			if (payload.previewProjection) return await handleProjectionPreviewRequest(config, payload.previewProjection);
+			const previewResponse = await handleIfPreview(payload);
+			if (previewResponse) return previewResponse;
 			if (payload.sample) await runSampleSync(payload.sample.entityKey, payload.runId);
 			else await runScheduled({
 				mode: payload.mode,
@@ -2445,10 +2615,17 @@ function createClivlySDK(config) {
 		runScheduled,
 		createClivlyHandler,
 		sync: runSync,
-		createAuthVerifyHandler
+		createAuthVerifyHandler,
+		pushOne
 	};
 }
 //#endregion
+Object.defineProperty(exports, "CURSOR_KEY_PREFIX", {
+	enumerable: true,
+	get: function() {
+		return CURSOR_KEY_PREFIX;
+	}
+});
 Object.defineProperty(exports, "ClivlyAuthError", {
 	enumerable: true,
 	get: function() {
@@ -2491,3 +2668,15 @@ Object.defineProperty(exports, "isPlaceholderUrl", {
 		return isPlaceholderUrl;
 	}
 });
+Object.defineProperty(exports, "kvCursorStore", {
+	enumerable: true,
+	get: function() {
+		return kvCursorStore;
+	}
+});
+Object.defineProperty(exports, "memoryCursorStore", {
+	enumerable: true,
+	get: function() {
+		return memoryCursorStore;
+	}
+});

package/sdk.cjs

@@ -1,6 +1,7 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_entity_config = require("./entity-config-BI4RYNKL.cjs");
-const require_sdk = require("./sdk-BvGSxBQc.cjs");
+const require_sdk = require("./sdk-ZMy4C4VK.cjs");
+exports.CURSOR_KEY_PREFIX = require_sdk.CURSOR_KEY_PREFIX;
 exports.ClivlyAuthError = require_sdk.ClivlyAuthError;
 exports.ClivlyError = require_sdk.ClivlyError;
 exports.ClivlyNetworkError = require_sdk.ClivlyNetworkError;
@@ -10,4 +11,6 @@ exports.createClivlySDK = require_sdk.createClivlySDK;
 exports.customObjectDeclarations = require_entity_config.customObjectDeclarations;
 exports.defineClivlyConfig = require_entity_config.defineClivlyConfig;
 exports.isPlaceholderUrl = require_sdk.isPlaceholderUrl;
+exports.kvCursorStore = require_sdk.kvCursorStore;
+exports.memoryCursorStore = require_sdk.memoryCursorStore;
 exports.validateEntitiesConfig = require_entity_config.validateEntitiesConfig;

package/sdk.d.cts

@@ -1,5 +1,5 @@
 import { C as customObjectDeclarations, M as validateEntitiesConfig, a as ClivlyEntitiesConfig, f as CustomObjectDeclaration, l as ConfigValidationError, m as DiscoveredSchemaTable, u as ConfigValidationResult, w as defineClivlyConfig } from "./entity-config-ApnT5j3X.cjs";
-import { _ as RemoteProjectionsDescription, a as ClivlyConnectResult, c as ClivlyUser, d as DiscoveredTable, f as DoctorCheck, g as EnsuredObjectTypeResult, h as EnsuredMappingResult, i as ClivlyConnectReason, l as CreateChatSessionHandlerOptions, m as EnsureSchemaResult, n as ChatSessionRequestBody, o as ClivlySDK, p as DoctorReport, r as ChatWidgetVisitor, s as ClivlySDKConfig, u as CursorStore, y as SyncTriggerDescription } from "./namespace-probe-C5RLl74M.cjs";
+import { _ as RemoteProjectionsDescription, a as ClivlyConnectResult, c as ClivlyUser, d as DiscoveredTable, f as DoctorCheck, g as EnsuredObjectTypeResult, h as EnsuredMappingResult, i as ClivlyConnectReason, l as CreateChatSessionHandlerOptions, m as EnsureSchemaResult, n as ChatSessionRequestBody, o as ClivlySDK, p as DoctorReport, r as ChatWidgetVisitor, s as ClivlySDKConfig, u as CursorStore, y as SyncTriggerDescription } from "./namespace-probe-H7yWc0JV.cjs";
 //#region ../sdk/src/trigger-url.d.ts
 export declare function isPlaceholderUrl(value: string): boolean;
 //#endregion
@@ -28,6 +28,38 @@ export declare class ClivlyRateLimitError extends ClivlyError {}
 export declare class ClivlyNetworkError extends ClivlyError {}
 //#endregion
 //#region ../sdk/src/index.d.ts
+export declare function memoryCursorStore(): CursorStore;
+/** The shape every key-value client shares: Workers KV, Upstash, node-redis. */
+export interface CursorKV {
+  get(key: string): Promise<string | null> | string | null;
+  put(key: string, value: string): Promise<unknown> | unknown;
+}
+/** Default key prefix for {@link kvCursorStore}. */
+export declare const CURSOR_KEY_PREFIX = "clivly:cursor:";
+/**
+ * A persistent `CursorStore` backed by any key-value store.
+ *
+ * Serverless runtimes discard memory between invocations, so without a
+ * persisted cursor every `delta` sync starts from `null` and re-reads the
+ * whole source table. That is invisible — the run succeeds — and bills like a
+ * full sync forever.
+ *
+ * This exists because the hand-written version has a trap in it:
+ * `SyncCursor.time` is a `Date`, which a JSON round-trip turns into a string,
+ * and `fromDrizzle` then calls `since.time.toISOString()` on it. The cursor is
+ * stored as an ISO string and parsed back to a `Date` here so no caller has to
+ * remember that.
+ *
+ * ```ts
+ * cursorStore: kvCursorStore(env.CLIVLY_CURSORS) // Workers KV binding
+ * ```
+ *
+ * A malformed or partial stored value resolves to `null` rather than throwing:
+ * the worst case is one full re-read, where throwing would wedge sync entirely.
+ */
+export declare function kvCursorStore(kv: CursorKV, options?: {
+  prefix?: string;
+}): CursorStore;
 /**
  * Create the Clivly SDK. The implemented surface — heartbeat/discovery reporting
  * and the auth-verify handler — connects a developer's app to a running Clivly

package/sdk.d.mts

@@ -1,5 +1,5 @@
 import { C as customObjectDeclarations, M as validateEntitiesConfig, a as ClivlyEntitiesConfig, f as CustomObjectDeclaration, l as ConfigValidationError, m as DiscoveredSchemaTable, u as ConfigValidationResult, w as defineClivlyConfig } from "./entity-config-CKcj4-M_.mjs";
-import { _ as RemoteProjectionsDescription, a as ClivlyConnectResult, c as ClivlyUser, d as DiscoveredTable, f as DoctorCheck, g as EnsuredObjectTypeResult, h as EnsuredMappingResult, i as ClivlyConnectReason, l as CreateChatSessionHandlerOptions, m as EnsureSchemaResult, n as ChatSessionRequestBody, o as ClivlySDK, p as DoctorReport, r as ChatWidgetVisitor, s as ClivlySDKConfig, u as CursorStore, y as SyncTriggerDescription } from "./namespace-probe-CNQKSmxz.mjs";
+import { _ as RemoteProjectionsDescription, a as ClivlyConnectResult, c as ClivlyUser, d as DiscoveredTable, f as DoctorCheck, g as EnsuredObjectTypeResult, h as EnsuredMappingResult, i as ClivlyConnectReason, l as CreateChatSessionHandlerOptions, m as EnsureSchemaResult, n as ChatSessionRequestBody, o as ClivlySDK, p as DoctorReport, r as ChatWidgetVisitor, s as ClivlySDKConfig, u as CursorStore, y as SyncTriggerDescription } from "./namespace-probe-DykR0kgh.mjs";
 //#region ../sdk/src/trigger-url.d.ts
 export declare function isPlaceholderUrl(value: string): boolean;
 //#endregion
@@ -28,6 +28,38 @@ export declare class ClivlyRateLimitError extends ClivlyError {}
 export declare class ClivlyNetworkError extends ClivlyError {}
 //#endregion
 //#region ../sdk/src/index.d.ts
+export declare function memoryCursorStore(): CursorStore;
+/** The shape every key-value client shares: Workers KV, Upstash, node-redis. */
+export interface CursorKV {
+  get(key: string): Promise<string | null> | string | null;
+  put(key: string, value: string): Promise<unknown> | unknown;
+}
+/** Default key prefix for {@link kvCursorStore}. */
+export declare const CURSOR_KEY_PREFIX = "clivly:cursor:";
+/**
+ * A persistent `CursorStore` backed by any key-value store.
+ *
+ * Serverless runtimes discard memory between invocations, so without a
+ * persisted cursor every `delta` sync starts from `null` and re-reads the
+ * whole source table. That is invisible — the run succeeds — and bills like a
+ * full sync forever.
+ *
+ * This exists because the hand-written version has a trap in it:
+ * `SyncCursor.time` is a `Date`, which a JSON round-trip turns into a string,
+ * and `fromDrizzle` then calls `since.time.toISOString()` on it. The cursor is
+ * stored as an ISO string and parsed back to a `Date` here so no caller has to
+ * remember that.
+ *
+ * ```ts
+ * cursorStore: kvCursorStore(env.CLIVLY_CURSORS) // Workers KV binding
+ * ```
+ *
+ * A malformed or partial stored value resolves to `null` rather than throwing:
+ * the worst case is one full re-read, where throwing would wedge sync entirely.
+ */
+export declare function kvCursorStore(kv: CursorKV, options?: {
+  prefix?: string;
+}): CursorStore;
 /**
  * Create the Clivly SDK. The implemented surface — heartbeat/discovery reporting
  * and the auth-verify handler — connects a developer's app to a running Clivly

package/sdk.mjs

@@ -1,3 +1,3 @@
 import { c as defineClivlyConfig, g as validateEntitiesConfig, s as customObjectDeclarations } from "./entity-config-Ccfb2IL9.mjs";
-import { a as ClivlyRateLimitError, i as ClivlyNetworkError, n as ClivlyAuthError, o as createChatSessionHandler, r as ClivlyError, s as isPlaceholderUrl, t as createClivlySDK } from "./sdk-C-Pjxj2y.mjs";
-export { ClivlyAuthError, ClivlyError, ClivlyNetworkError, ClivlyRateLimitError, createChatSessionHandler, createClivlySDK, customObjectDeclarations, defineClivlyConfig, isPlaceholderUrl, validateEntitiesConfig };
+import { a as ClivlyAuthError, c as ClivlyRateLimitError, i as memoryCursorStore, l as createChatSessionHandler, n as createClivlySDK, o as ClivlyError, r as kvCursorStore, s as ClivlyNetworkError, t as CURSOR_KEY_PREFIX, u as isPlaceholderUrl } from "./sdk-DLoVPlGB.mjs";
+export { CURSOR_KEY_PREFIX, ClivlyAuthError, ClivlyError, ClivlyNetworkError, ClivlyRateLimitError, createChatSessionHandler, createClivlySDK, customObjectDeclarations, defineClivlyConfig, isPlaceholderUrl, kvCursorStore, memoryCursorStore, validateEntitiesConfig };