clivly 0.13.0 → 0.14.1

package/internal.mjs

@@ -6,6 +6,6 @@ import { a as hostOwnedFieldMessage, c as rejectedContactFields, i as toObjectTy
 import { n as buildRelationships, r as relationshipViaSignature, t as buildFilterFromDiscriminator } from "./mapping-form-DigkuvFc.mjs";
 import { a as compileProjectionPreview, i as compileProjectionJoins, n as compileProjectionFrom, o as compileProjectionSelect, r as compileProjectionIdentity, s as quoteIdent, t as PREVIEW_MAX_ROWS } from "./projection-sql-DweUaWRc.mjs";
 import { i as explainEntitiesConfig, n as compileEntityView, r as compileEntityViews, t as DEFAULT_VIEW_PREFIX } from "./view-compiler-C-6RydKK.mjs";
-import { i as runSync, r as reconcile } from "./sync-engine-Df2MCs_n.mjs";
+import { a as resolveActions, i as reconcile, n as isRemovalAction, o as runSync } from "./sync-engine-DH058G3w.mjs";
 import { n as isClosedStageType, t as OPEN_STAGE_TYPE } from "./types-YJTkXKzU.mjs";
-export { BASE_REF, CANONICAL_FIELDS, CRM_CONCEPTS, ClivlyConfigError, DEFAULT_VIEW_PREFIX, MATERIALIZING_CONCEPTS, OPEN_STAGE_TYPE, PREVIEW_MAX_ROWS, PROJECTION_KEY_PATTERN, REQUIRED_FIELDS, authCustom, buildFilterFromDiscriminator, buildRelationships, columnMetaFor, compileEntityView, compileEntityViews, compileProjectionFrom, compileProjectionIdentity, compileProjectionJoins, compileProjectionPreview, compileProjectionSelect, computeDealValue, coversUniqueKey, defineClivlyConfig, entitiesConfigSchema, evaluateStage, explainEntitiesConfig, fanOutJoins, filterSchema, hasRichMeta, hostOwnedFieldMessage, identityRefs, isClosedStageType, isHostOwned, joinFansOut, mappingsToEntitiesConfig, matchesCondition, missingRequiredFields, primaryKeyColumns, projectionFields, projectionSchema, quoteIdent, reconcile, rejectedCompanyFields, rejectedContactFields, relationshipSchema, relationshipViaSignature, relationshipsSchema, requiredFieldsFor, runSync, slugify, toObjectTypeSlug, validateEntitiesConfig, validateProjection, validateProjectionFilter };
+export { BASE_REF, CANONICAL_FIELDS, CRM_CONCEPTS, ClivlyConfigError, DEFAULT_VIEW_PREFIX, MATERIALIZING_CONCEPTS, OPEN_STAGE_TYPE, PREVIEW_MAX_ROWS, PROJECTION_KEY_PATTERN, REQUIRED_FIELDS, authCustom, buildFilterFromDiscriminator, buildRelationships, columnMetaFor, compileEntityView, compileEntityViews, compileProjectionFrom, compileProjectionIdentity, compileProjectionJoins, compileProjectionPreview, compileProjectionSelect, computeDealValue, coversUniqueKey, defineClivlyConfig, entitiesConfigSchema, evaluateStage, explainEntitiesConfig, fanOutJoins, filterSchema, hasRichMeta, hostOwnedFieldMessage, identityRefs, isClosedStageType, isHostOwned, isRemovalAction, joinFansOut, mappingsToEntitiesConfig, matchesCondition, missingRequiredFields, primaryKeyColumns, projectionFields, projectionSchema, quoteIdent, reconcile, rejectedCompanyFields, rejectedContactFields, relationshipSchema, relationshipViaSignature, relationshipsSchema, requiredFieldsFor, resolveActions, runSync, slugify, toObjectTypeSlug, validateEntitiesConfig, validateProjection, validateProjectionFilter };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clivly",
-  "version": "0.13.0",
+  "version": "0.14.1",
   "private": false,
   "type": "module",
   "description": "Clivly CLI — scaffold a CRM into your app (clivly init).",

package/{sdk-B-dp1tZN.mjs → sdk-DLoVPlGB.mjs}

@@ -1391,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]/;
@@ -1702,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,
@@ -1711,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;
@@ -1940,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,
@@ -2368,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,
@@ -2379,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,
@@ -2486,4 +2620,4 @@ function createClivlySDK(config) {
 	};
 }
 //#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-DKfKhJD_.cjs → sdk-ZMy4C4VK.cjs}

@@ -1391,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]/;
@@ -1702,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,
@@ -1711,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;
@@ -1940,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,
@@ -2368,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,
@@ -2379,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,
@@ -2486,6 +2620,12 @@ function createClivlySDK(config) {
 	};
 }
 //#endregion
+Object.defineProperty(exports, "CURSOR_KEY_PREFIX", {
+	enumerable: true,
+	get: function() {
+		return CURSOR_KEY_PREFIX;
+	}
+});
 Object.defineProperty(exports, "ClivlyAuthError", {
 	enumerable: true,
 	get: function() {
@@ -2528,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-DKfKhJD_.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

@@ -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

@@ -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-B-dp1tZN.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 };