@clivly/sdk 0.13.0 → 0.15.0

package/README.md

@@ -272,10 +272,16 @@ production runtimes.
 // Cloudflare Workers
 export default {
   scheduled: () => clivly.runScheduled(), // cron: one heartbeat + one sync
-  fetch: clivly.createClivlyHandler(),    // or drive via an uptime ping
+  fetch: clivly.createClivlyHandler(),    // the route Clivly Cloud POSTs to
 };
 ```
 
+**Only `POST` triggers a sync.** `HEAD` answers `204` and does no work — that
+is the liveness probe. `GET` still syncs but logs a deprecation warning, and a
+future release will refuse it with `405`, so point any cron or uptime check at
+`POST`. Set `CLIVLY_TRIGGER_REQUIRE_POST=true` to adopt that now and confirm
+nothing in your setup depends on `GET`.
+
 `runScheduled()` throws if a sync push fails, so a cron run is marked failed.
 `createClivlyHandler()` returns `200` when the triggered run finishes
 successfully and `500` otherwise, with `{ ok, runId, durationMs }` or
@@ -350,7 +356,8 @@ it, dashboard-authored objects are fetched and then skipped; nothing errors, and
 | Nothing connects, no error | You imported the config but never called an entry point | Call `start()` / `runScheduled()`, or add `clivlyVite(sdk)` |
 | `reason: "invalid_api_key"` | `CLIVLY_SECRET_KEY` missing, wrong, or revoked by a regeneration | Re-run `npx clivly login` |
 | Sync works once on serverless, then stops | `start()`'s `setInterval` cannot persist | Use `runScheduled()` or `createClivlyHandler()` |
-| Every cold start re-reads everything | The default cursor store is in-memory | Pass a persistent [`cursorStore`](#persisting-the-delta-cursor) |
+| Every run re-reads everything | The default cursor store is in-memory, which serverless discards between invocations | Pass [`kvCursorStore`](#persisting-the-delta-cursor) |
+| A cron stopped triggering syncs | Only `POST` triggers a sync | Change the caller to `POST` |
 | `401` on the tick route | Trigger secret differs between your app and Clivly | Redeploy with the current `CLIVLY_SYNC_TRIGGER_SECRET` |
 | An entity syncs nothing, silently | `source` keyed by entity key instead of CRM concept | Key it `contacts` / `companies` / `deals` / `custom` |
 | Rows sync on insert but never on edit | `cursorField` does not change on edit | Add an `updated_at` column and use it. `doctor()` warns about this |
@@ -372,35 +379,92 @@ failed `connect()` result into a throwable.
 
 Delta sync tracks a per-entity cursor so each run only pages rows changed since
 the last one. By default that cursor lives in memory — fine for a long-lived
-process, but **lost on every serverless cold start**, so a fresh isolate would
-re-page the whole entity.
+process, but **discarded between invocations on serverless**. Every delta run
+then starts from nothing and re-reads your entire source tables: a full sync,
+on every run, reported as a success. The SDK warns at startup when it detects a
+serverless runtime with no `cursorStore`, and `clivly status` flags it.
+
+Use the store the SDK ships. It works with any key-value client that has `get`
+and `put` — Workers KV, Upstash, node-redis:
 
 ```ts
+import { createClivlySDK, kvCursorStore } from "@clivly/sdk";
+
 const clivly = createClivlySDK({
   apiKey: process.env.CLIVLY_SECRET_KEY!,
   entities,
   source: { /* … */ },
-  cursorStore: {
-    // `SyncCursor` is { id: string; time: Date } — serialize `time` yourself.
-    get: async (entity) => {
-      const raw = await kv.get(`clivly:cursor:${entity}`);
-      return raw ? { id: raw.id, time: new Date(raw.time) } : null;
-    },
-    set: (entity, cursor) =>
-      kv.put(
-        `clivly:cursor:${entity}`,
-        cursor && { id: cursor.id, time: cursor.time.toISOString() }
-      ),
-  },
+  cursorStore: kvCursorStore(env.CLIVLY_CURSORS),
 });
 ```
 
+Writing your own is fine too, but mind the one trap: **`SyncCursor.time` is a
+`Date`**. A JSON round-trip turns it into a string, and the sync path then
+calls `.toISOString()` on it and throws. Serialize to ISO on the way out and
+parse back to a `Date` on the way in — which is exactly what `kvCursorStore`
+does for you:
+
+```ts
+cursorStore: {
+  get: async (entity) => {
+    const raw = await kv.get(`clivly:cursor:${entity}`);
+    if (!raw) return null;
+    const { id, time } = JSON.parse(raw);
+    return { id, time: new Date(time) }; // back to a Date
+  },
+  set: (entity, cursor) =>
+    kv.put(
+      `clivly:cursor:${entity}`,
+      cursor ? JSON.stringify({ id: cursor.id, time: cursor.time.toISOString() }) : ""
+    ),
+}
+```
+
+Return `null` rather than throwing on a missing or malformed value: the cost is
+one full re-read, where throwing would stop sync entirely.
+
+`memoryCursorStore()` is also exported, for tests and for long-lived hosts that
+want the default named explicitly.
+
 Delta sync is **at-least-once**: after a cold start with no persisted cursor,
 rows since the last push may be re-sent (the server dedupes by id) — it never
 silently skips rows. Use `sync({ mode: "full" })` when you need the server to
 reconcile deletions (archive-on-leave); a delta cannot tell absence from
 "unchanged".
 
+### Pushing a row the moment it is written
+
+Scheduled syncs pick new rows up eventually. To push one immediately (a signup,
+say), opt in with `sync: { instant: true }` and wrap the insert with
+`insertAndPush`. You create it once per mapped table, and it inserts,
+translates the row and pushes it. Without the opt-in, both helpers do nothing
+and the row arrives on the next delta sync instead. The `entity` argument is
+the key from your `entities` config. A push never throws: a failed push only
+logs a warning, and the next delta sync still delivers the row.
+
+```ts
+import { insertAndPush } from "clivly/drizzle";
+
+const insertUser = insertAndPush(clivly, db, schema.users, { entity: "user" });
+
+// In the signup handler. Pass `waitUntil` on Workers so the push outlives the response.
+const created = await insertUser(newUserValues, c.executionCtx.waitUntil.bind(c.executionCtx));
+```
+
+When a library performs the insert itself (an auth library's lifecycle hook,
+for example) there is no call to wrap. Re-read the row and translate it with
+`toColumnKeyedRow`, then push it:
+
+```ts
+import { toColumnKeyedRow } from "clivly/drizzle";
+
+await clivly.pushOne("user", toColumnKeyedRow(schema.users, row));
+```
+
+The translation matters. A Drizzle row is keyed by property name (`fullName`),
+but mappings and the cloud address columns by their database name
+(`full_name`), so an untranslated row pushes empty fields without any error.
+
 ### Sync ordering
 
 `runSync` pushes **companies first**, then contacts, then deals, then custom
@@ -418,9 +482,17 @@ membership**, each row carrying the join table's foreign-key column.
 { id: "u1", full_name: "Ada", email: "ada@acme.test", org_id: "globex" }
 ```
 
-This mirrors what the embedded model produces with `LEFT JOIN <join table>`, and
-it is what lets Clivly keep one CRM row per membership instead of collapsing the
-person onto whichever company happened to come first.
+This mirrors what the embedded model produces with `LEFT JOIN <join table>`.
+Clivly keeps Ada as **one contact** (identity is her `id`, not `id` + company)
+with **two memberships**, one per organisation. The contact list shows her once,
+as `Acme +1`, and both organisations' contact counts include her. Her primary
+organisation is the lowest company ref for a new contact, and it stays put
+while she still belongs to it.
+
+When she leaves one organisation, a **full** sync ends that membership and
+keeps the contact and her other memberships live. A delta sync never ends a
+membership, because a missing row may just be on the next page of the push.
+She is archived only when she leaves the source entirely.
 
 A person with no membership may omit the column entirely or send it as `null` —
 both are accepted. But if **no** pushed row carries the column, the push is
@@ -450,13 +522,14 @@ is honoured. Other `4xx` responses return immediately.
 | `entities` | `ClivlyEntitiesConfig` | — | From `defineClivlyConfig({ entities })` |
 | `schema` | `DiscoveredTable[]` | — | Use `discoverFromDrizzle(schema)`. It reports keys, types, nullability and FK edges alongside column names; [derived objects](#derived-objects) cannot be authored without them, so prefer it over a hand-written array |
 | `source` | `{ contacts, companies?, deals?, custom? }` | — | Keyed by CRM concept. `contacts` is required when `source` is present |
-| `cursorStore` | `CursorStore` | in-memory | Persist on serverless |
+| `cursorStore` | `CursorStore` | in-memory | **Required on serverless** — `kvCursorStore(kv)` |
 | `heartbeatIntervalMs` | `number` | `60000` | HTTP presence cadence and default sync cadence; paused when opt-in WebSocket presence is ready |
 | `presence.transport` | `"http" \\| "websocket"` | `"http"` | WebSocket is for long-lived Node hosts; HTTP resumes during reconnect/fallback |
 | `presence.deploymentId` | `string` | platform-derived | Optional release identity for a WebSocket deployment |
 | `sync.onBoot` | `boolean` | `true` | Only affects `start()` |
 | `sync.intervalMs` | `number` | `heartbeatIntervalMs` | |
 | `sync.batchSize` | `number` | `500` | Rows per page |
+| `sync.instant` | `boolean` | `false` | Lets `pushOne()` / `insertAndPush()` push a single row immediately; see [Pushing a row the moment it is written](#pushing-a-row-the-moment-it-is-written) |
 | `retry.maxAttempts` / `retry.baseDelayMs` | `number` | `3` / `500` | |
 | `syncTrigger.path` / `.url` / `.secret` | `string` | — | See above |
 | `verifyToken` | `string` | — | For `createAuthVerifyHandler`. **Nothing calls that endpoint today** |
@@ -518,7 +591,7 @@ rejected key and a dead network all mean the question went unanswered.
 | From `clivly` | From `@clivly/sdk` | Contents |
 | --- | --- | --- |
 | `clivly/sdk` | `@clivly/sdk` | `createClivlySDK`, `defineClivlyConfig`, `createChatSessionHandler`, error classes, all types |
-| `clivly/drizzle` | `@clivly/sdk/drizzle` | `fromDrizzle`, `discoverFromDrizzle`, `drizzleIntrospector`, `buildUniqueConstraints` |
+| `clivly/drizzle` | `@clivly/sdk/drizzle` | `fromDrizzle`, `discoverFromDrizzle`, `drizzleIntrospector`, `buildUniqueConstraints`, `insertAndPush`, `toColumnKeyedRow` |
 | `clivly/vite` | `@clivly/sdk/vite` | `clivlyVite` |
 | — | `@clivly/sdk/chat-session` | `createChatSessionHandler` (also on the root) |
 

package/dist/index.cjs

@@ -1393,6 +1393,51 @@ async function fullSyncSource(args) {
 	};
 }
 //#endregion
+//#region 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 src/trigger-url.ts
 const SCHEME_REGEX = /^https?:\/\//;
 const INVALID_HOST_CHARS_REGEX = /[/\\@?#\s]/;
@@ -1584,7 +1629,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,
@@ -1593,6 +1638,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;
@@ -1822,9 +1917,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,
@@ -2250,8 +2347,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,
@@ -2261,8 +2395,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,
@@ -2368,6 +2502,7 @@ function createClivlySDK(config) {
 	};
 }
 //#endregion
+exports.CURSOR_KEY_PREFIX = CURSOR_KEY_PREFIX;
 exports.ClivlyAuthError = ClivlyAuthError;
 exports.ClivlyError = ClivlyError;
 exports.ClivlyNetworkError = ClivlyNetworkError;
@@ -2387,6 +2522,8 @@ Object.defineProperty(exports, "defineClivlyConfig", {
 	}
 });
 exports.isPlaceholderUrl = isPlaceholderUrl;
+exports.kvCursorStore = kvCursorStore;
+exports.memoryCursorStore = memoryCursorStore;
 Object.defineProperty(exports, "validateEntitiesConfig", {
 	enumerable: true,
 	get: function() {

package/dist/index.d.cts

@@ -26,6 +26,38 @@ export declare class ClivlyRateLimitError extends ClivlyError {}
 export declare class ClivlyNetworkError extends ClivlyError {}
 //#endregion
 //#region 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/dist/index.d.mts

@@ -26,6 +26,38 @@ export declare class ClivlyRateLimitError extends ClivlyError {}
 export declare class ClivlyNetworkError extends ClivlyError {}
 //#endregion
 //#region 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/dist/index.mjs

@@ -1392,6 +1392,51 @@ async function fullSyncSource(args) {
 	};
 }
 //#endregion
+//#region 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 src/trigger-url.ts
 const SCHEME_REGEX = /^https?:\/\//;
 const INVALID_HOST_CHARS_REGEX = /[/\\@?#\s]/;
@@ -1583,7 +1628,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,
@@ -1592,6 +1637,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;
@@ -1821,9 +1916,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,
@@ -2249,8 +2346,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,
@@ -2260,8 +2394,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,
@@ -2367,4 +2501,4 @@ function createClivlySDK(config) {
 	};
 }
 //#endregion
-export { ClivlyAuthError, ClivlyError, ClivlyNetworkError, ClivlyRateLimitError, createChatSessionHandler, createClivlySDK, customObjectDeclarations, defineClivlyConfig, isPlaceholderUrl, validateEntitiesConfig };
+export { CURSOR_KEY_PREFIX, ClivlyAuthError, ClivlyError, ClivlyNetworkError, ClivlyRateLimitError, createChatSessionHandler, createClivlySDK, customObjectDeclarations, defineClivlyConfig, isPlaceholderUrl, kvCursorStore, memoryCursorStore, validateEntitiesConfig };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clivly/sdk",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "private": false,
   "description": "Clivly SDK — connect your app to Clivly Cloud (heartbeat, discovery, auth bridge).",
   "license": "MIT",
@@ -53,14 +53,14 @@
     "README.md"
   ],
   "dependencies": {
-    "@clivly/core": "0.13.0"
+    "@clivly/core": "0.15.0"
   },
   "devDependencies": {
     "@electric-sql/pglite": "^0.5.4",
     "drizzle-orm": "^0.45.2",
     "tsdown": "^0.23.0",
     "typescript": "^6",
-    "vite": "^8.3.0",
+    "vite": "^8.3.5",
     "vitest": "^3.2.0"
   },
   "peerDependencies": {