@clivly/sdk 0.1.0 → 0.2.0

package/README.md

@@ -14,39 +14,107 @@ npm install @clivly/sdk
 
 ```ts
 import { createClivlySDK } from "@clivly/sdk";
-import { and, gt } from "drizzle-orm";
+import { fromDrizzle } from "@clivly/sdk/drizzle";
+import { defineClivlyConfig } from "@clivly/core";
 import { db, participants, accounts } from "./db";
 
+// Declarative entity config — the non-deprecated source of truth. It maps your
+// host tables/columns onto CRM concepts, and `defineClivlyConfig` validates it
+// at load (warning on any non-canonical field key that would mirror as empty).
+const entities = defineClivlyConfig({
+  entities: {
+    participants: {
+      concept: "contact",
+      source: "participants",
+      fields: { name: "full_name", email: "email" },
+    },
+    accounts: {
+      concept: "company",
+      source: "accounts",
+      fields: { name: "legal_name", domain: "website" },
+    },
+  },
+});
+
 const clivly = createClivlySDK({
   apiKey: process.env.CLIVLY_API_KEY!, // sk_live_… from Settings → API keys
-  contactEntity: "participants",
-  contactFields: ["id", "full_name", "email", "account_id", "updated_at"],
+  entities,
   source: {
-    contacts: {
-      entity: "participants",
-      cursorField: "updated_at",
-      fetchPage: ({ since, limit }) =>
-        db.select().from(participants)
-          .where(since ? gt(participants.updated_at, since) : undefined)
-          .orderBy(participants.updated_at)
-          .limit(limit),
-    },
-    companies: {
-      entity: "accounts",
-      cursorField: "updated_at",
-      fetchPage: ({ since, limit }) =>
-        db.select().from(accounts)
-          .where(since ? gt(accounts.updated_at, since) : undefined)
-          .orderBy(accounts.updated_at)
-          .limit(limit),
-    },
+    contacts: fromDrizzle(db, participants, { entity: "participants", cursorField: "updated_at" }),
+    companies: fromDrizzle(db, accounts, { entity: "accounts", cursorField: "updated_at" }),
   },
   sync: { onBoot: true, intervalMs: 30_000, batchSize: 500 },
 });
 
+const status = await clivly.connect(); // rich result: { ok, status, reason, retryable, org? }
+if (!status.ok) throw new Error(`Clivly: ${status.reason}`);
 await clivly.start();      // heartbeat + backfill + interval delta sync
-await clivly.sync();       // force a delta sync now
 ```
 
-`fetchPage` returns rows keyed by your source column names. Clivly applies the
-field map you confirmed during onboarding, so re-mapping never needs a redeploy.
+`fromDrizzle` generates the keyset-paginated `fetchPage` the SDK needs, inferring the
+tie-breaker id from the table's primary key — pass `idField` to override. Rows are keyed by
+your source column names; Clivly applies the field map you confirmed during onboarding, so
+re-mapping never needs a redeploy. Non-Drizzle hosts can still pass a hand-written
+`fetchPage` closure instead.
+
+> **Legacy:** the flat `contactEntity` / `contactFields` form is still accepted but
+> **deprecated** — prefer the `entities` config above, which is the same model the
+> mapping table and sync engine share.
+
+## Verify your setup
+
+Put your instance in `clivly.config.ts` (`export default createClivlySDK({...})`), then:
+
+```bash
+npx clivly doctor   # env → config → schema → columns → sample fetch → heartbeat
+```
+
+Or in code: `await clivly.doctor()` returns `{ ok, checks }` — the same six read-only checks.
+
+## Serverless / edge
+
+On request-scoped runtimes (Cloudflare Workers, Vercel, Lambda) there is no long-lived
+process, so `start()`'s `setInterval` keep-alive loop can't persist — it stops ticking after
+the first response. **Don't call `start()` there.** Instead drive one-shot runs from a
+scheduled trigger with `runScheduled()`, or mount `createClivlyHandler()` at a route:
+
+```ts
+// Cloudflare Workers
+export default {
+  scheduled: () => clivly.runScheduled(), // cron: one heartbeat + one sync
+  fetch: clivly.createClivlyHandler(),    // or drive via an uptime ping / external scheduler
+};
+```
+
+`runScheduled()` throws if a sync push fails (so a cron run is marked failed);
+`createClivlyHandler()` returns `200` on success, `500` otherwise. `start()` emits a warning
+if it detects a serverless runtime. Verify a connection from the terminal any time with
+`npx clivly ping`.
+
+### Persisting the delta cursor
+
+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. Pass a
+`cursorStore` backed by your own KV/DB to persist it:
+
+```ts
+const clivly = createClivlySDK({
+  apiKey: process.env.CLIVLY_API_KEY!,
+  entities,
+  source: { /* … */ },
+  cursorStore: {
+    // `SyncCursor` is { id: string; time: Date } — serialize `time` (e.g. ISO string).
+    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() }),
+  },
+});
+```
+
+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).

package/dist/drizzle-meta-C0T6F3vL.cjs

@@ -0,0 +1,9 @@
+//#region src/drizzle-meta.ts
+const DRIZZLE_META = Symbol("clivly.drizzleSourceMeta");
+//#endregion
+Object.defineProperty(exports, "DRIZZLE_META", {
+	enumerable: true,
+	get: function() {
+		return DRIZZLE_META;
+	}
+});

package/dist/drizzle-meta-CAJ43cLc.mjs

@@ -0,0 +1,4 @@
+//#region src/drizzle-meta.ts
+const DRIZZLE_META = Symbol("clivly.drizzleSourceMeta");
+//#endregion
+export { DRIZZLE_META as t };

package/dist/drizzle.cjs

@@ -0,0 +1,50 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_drizzle_meta = require("./drizzle-meta-C0T6F3vL.cjs");
+let drizzle_orm = require("drizzle-orm");
+//#region src/drizzle.ts
+function inferIdField(table) {
+	const columns = (0, drizzle_orm.getTableColumns)(table);
+	const primaryKeys = Object.entries(columns).filter(([, column]) => column.primary);
+	if (primaryKeys.length === 1) {
+		const primaryKeyField = primaryKeys[0]?.[0];
+		if (!primaryKeyField) throw new Error(`fromDrizzle: unable to extract primary key field name from table "${(0, drizzle_orm.getTableName)(table)}".`);
+		return primaryKeyField;
+	}
+	const kind = primaryKeys.length === 0 ? "no" : "a composite";
+	throw new Error(`fromDrizzle: table "${(0, drizzle_orm.getTableName)(table)}" has ${kind} single-column primary key — pass { idField } explicitly.`);
+}
+/**
+* Build a `SyncSource` from a Drizzle table, generating the keyset-paginated
+* `fetchPage` the SDK needs. `cursorField`/`idField` are drizzle property keys;
+* `idField` defaults to the table's single-column primary key.
+*
+* `drizzle-orm` is an optional peer dependency — installed only when you import
+* `@clivly/sdk/drizzle`.
+*/
+function fromDrizzle(db, table, opts) {
+	const drizzleDb = db;
+	const idField = opts.idField ?? inferIdField(table);
+	const columns = (0, drizzle_orm.getTableColumns)(table);
+	const cursorColumn = columns[opts.cursorField];
+	const idColumn = columns[idField];
+	if (!cursorColumn) throw new Error(`fromDrizzle: cursorField "${opts.cursorField}" is not a column on "${(0, drizzle_orm.getTableName)(table)}".`);
+	if (!idColumn) throw new Error(`fromDrizzle: idField "${idField}" is not a column on "${(0, drizzle_orm.getTableName)(table)}".`);
+	const source = {
+		entity: opts.entity,
+		cursorField: opts.cursorField,
+		idField,
+		fetchPage: ({ since, limit }) => drizzleDb.select().from(table).where(since ? drizzle_orm.sql`(${cursorColumn}, ${idColumn}) > (${since.time}, ${since.id})` : void 0).orderBy((0, drizzle_orm.asc)(cursorColumn), (0, drizzle_orm.asc)(idColumn)).limit(limit)
+	};
+	const meta = {
+		columnKeys: Object.keys(columns),
+		cursorField: opts.cursorField,
+		idField
+	};
+	Object.defineProperty(source, require_drizzle_meta.DRIZZLE_META, {
+		value: meta,
+		enumerable: false
+	});
+	return source;
+}
+//#endregion
+exports.fromDrizzle = fromDrizzle;

package/dist/drizzle.d.cts

@@ -0,0 +1,22 @@
+import { u as SyncSource } from "./types-B0aSxJ6V.cjs";
+import { Table } from "drizzle-orm";
+
+//#region src/drizzle.d.ts
+interface DrizzleDb {
+  select: (...args: any[]) => any;
+}
+/**
+ * Build a `SyncSource` from a Drizzle table, generating the keyset-paginated
+ * `fetchPage` the SDK needs. `cursorField`/`idField` are drizzle property keys;
+ * `idField` defaults to the table's single-column primary key.
+ *
+ * `drizzle-orm` is an optional peer dependency — installed only when you import
+ * `@clivly/sdk/drizzle`.
+ */
+declare function fromDrizzle(db: DrizzleDb, table: Table, opts: {
+  entity: string;
+  cursorField: string;
+  idField?: string;
+}): SyncSource;
+//#endregion
+export { fromDrizzle };

package/dist/drizzle.d.mts

@@ -0,0 +1,22 @@
+import { u as SyncSource } from "./types-DWt-ytBQ.mjs";
+import { Table } from "drizzle-orm";
+
+//#region src/drizzle.d.ts
+interface DrizzleDb {
+  select: (...args: any[]) => any;
+}
+/**
+ * Build a `SyncSource` from a Drizzle table, generating the keyset-paginated
+ * `fetchPage` the SDK needs. `cursorField`/`idField` are drizzle property keys;
+ * `idField` defaults to the table's single-column primary key.
+ *
+ * `drizzle-orm` is an optional peer dependency — installed only when you import
+ * `@clivly/sdk/drizzle`.
+ */
+declare function fromDrizzle(db: DrizzleDb, table: Table, opts: {
+  entity: string;
+  cursorField: string;
+  idField?: string;
+}): SyncSource;
+//#endregion
+export { fromDrizzle };

package/dist/drizzle.mjs

@@ -0,0 +1,49 @@
+import { t as DRIZZLE_META } from "./drizzle-meta-CAJ43cLc.mjs";
+import { asc, getTableColumns, getTableName, sql } from "drizzle-orm";
+//#region src/drizzle.ts
+function inferIdField(table) {
+	const columns = getTableColumns(table);
+	const primaryKeys = Object.entries(columns).filter(([, column]) => column.primary);
+	if (primaryKeys.length === 1) {
+		const primaryKeyField = primaryKeys[0]?.[0];
+		if (!primaryKeyField) throw new Error(`fromDrizzle: unable to extract primary key field name from table "${getTableName(table)}".`);
+		return primaryKeyField;
+	}
+	const kind = primaryKeys.length === 0 ? "no" : "a composite";
+	throw new Error(`fromDrizzle: table "${getTableName(table)}" has ${kind} single-column primary key — pass { idField } explicitly.`);
+}
+/**
+* Build a `SyncSource` from a Drizzle table, generating the keyset-paginated
+* `fetchPage` the SDK needs. `cursorField`/`idField` are drizzle property keys;
+* `idField` defaults to the table's single-column primary key.
+*
+* `drizzle-orm` is an optional peer dependency — installed only when you import
+* `@clivly/sdk/drizzle`.
+*/
+function fromDrizzle(db, table, opts) {
+	const drizzleDb = db;
+	const idField = opts.idField ?? inferIdField(table);
+	const columns = getTableColumns(table);
+	const cursorColumn = columns[opts.cursorField];
+	const idColumn = columns[idField];
+	if (!cursorColumn) throw new Error(`fromDrizzle: cursorField "${opts.cursorField}" is not a column on "${getTableName(table)}".`);
+	if (!idColumn) throw new Error(`fromDrizzle: idField "${idField}" is not a column on "${getTableName(table)}".`);
+	const source = {
+		entity: opts.entity,
+		cursorField: opts.cursorField,
+		idField,
+		fetchPage: ({ since, limit }) => drizzleDb.select().from(table).where(since ? sql`(${cursorColumn}, ${idColumn}) > (${since.time}, ${since.id})` : void 0).orderBy(asc(cursorColumn), asc(idColumn)).limit(limit)
+	};
+	const meta = {
+		columnKeys: Object.keys(columns),
+		cursorField: opts.cursorField,
+		idField
+	};
+	Object.defineProperty(source, DRIZZLE_META, {
+		value: meta,
+		enumerable: false
+	});
+	return source;
+}
+//#endregion
+export { fromDrizzle };