@clivly/sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Clivly
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,52 @@
+# @clivly/sdk
+
+Connect your app to Clivly Cloud. The SDK sends a heartbeat, reports your schema
+for entity mapping, and mirrors your contacts and companies into Clivly — over
+outbound HTTPS only (no inbound ports, no tunnel).
+
+## Install
+
+```bash
+npm install @clivly/sdk
+```
+
+## Usage
+
+```ts
+import { createClivlySDK } from "@clivly/sdk";
+import { and, gt } from "drizzle-orm";
+import { db, participants, accounts } from "./db";
+
+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"],
+  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),
+    },
+  },
+  sync: { onBoot: true, intervalMs: 30_000, batchSize: 500 },
+});
+
+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.

package/dist/index.d.mts

@@ -0,0 +1,138 @@
+import { ClivlyEntitiesConfig } from "@clivly/core";
+
+//#region src/types.d.ts
+interface DiscoveredTable {
+  columns: string[];
+  name: string;
+}
+interface ClivlySDKConfig {
+  /** Org-scoped API token (sk_live_…) from Settings → API keys. */
+  apiKey: string;
+  /** Clivly API base URL. Defaults to https://api.clivly.com. */
+  apiUrl?: string;
+  /**
+   * The host table Clivly treats as the contact entity.
+   * @deprecated Prefer `entities` — the same mapping-derived shape
+   * `crm_entity_mappings` (and `@clivly/core`'s `mappingsToEntitiesConfig`)
+   * produce, so the SDK, the mappings table, and the sync engine share one
+   * model. A bare `contactEntity` is treated as a single contact entity.
+   */
+  contactEntity?: string;
+  /** Which columns of the contact entity Clivly may read. */
+  contactFields?: string[];
+  /**
+   * Declarative entity config — the single source of truth shared with
+   * `crm_entity_mappings`. When set, discovery and heartbeat are derived from
+   * it (each entity's `source` table + mapped columns), superseding the flat
+   * `contactEntity`.
+   */
+  entities?: ClivlyEntitiesConfig;
+  /** Reported to the portal so it can show the detected stack. */
+  framework?: string;
+  /** Heartbeat cadence in ms. Defaults to 60s. */
+  heartbeatIntervalMs?: number;
+  /** Whether the crm_* namespace exists in the host DB (self-reported). */
+  namespaceReady?: boolean;
+  orm?: string;
+  /**
+   * Network retry policy for outbound calls (heartbeat + sync push). Transient
+   * failures (network errors, HTTP 429, HTTP 5xx) are retried with exponential
+   * backoff + jitter; a `Retry-After` header on a 429 is honoured. Non-transient
+   * responses (e.g. 4xx other than 429) are returned immediately, not retried.
+   */
+  retry?: {
+    /** Total attempts including the first. Defaults to 3. Min 1. */maxAttempts?: number; /** Base backoff in ms (doubled each attempt). Defaults to 500. */
+    baseDelayMs?: number;
+  };
+  /** Tables/columns to report for entity discovery + mapping. */
+  schema?: DiscoveredTable[];
+  sdkVersion?: string;
+  /** Host entities to mirror into Clivly Cloud. */
+  source?: {
+    contacts: SyncSource;
+    companies?: SyncSource;
+  };
+  sync?: {
+    onBoot?: boolean;
+    /**
+     * Sync cadence in ms for the background keep-alive loop. Defaults to
+     * `heartbeatIntervalMs` (60s) so sync and heartbeat share a tick unless you
+     * decouple them — e.g. a slow full-mirror alongside frequent heartbeats.
+     */
+    intervalMs?: number;
+    batchSize?: number;
+  };
+  /** Cloudflare Tunnel token — reserved for write-back/tunnel mode. */
+  tunnelToken?: string;
+  /**
+   * Shared secret Clivly Cloud presents (as `Authorization: Bearer <token>`) when
+   * calling the `/clivly/auth/verify` endpoint. Required for the verify handler to
+   * authenticate the caller; without it the handler fails closed (HTTP 500).
+   */
+  verifyToken?: string;
+  writeBack?: {
+    enabled?: boolean; /** Only crm_* tables are ever accepted; this narrows further. */
+    tables?: string[];
+  };
+}
+interface ClivlyUser {
+  email: string;
+  id: string;
+  name?: string;
+}
+interface SyncCursor {
+  /** The row's id, breaking ties when timestamps collide. */
+  id: string;
+  /** The row's cursor-field value (typically `updated_at`). */
+  time: Date;
+}
+interface SyncSource {
+  cursorField: string;
+  entity: string;
+  fetchPage(args: {
+    since: SyncCursor | null;
+    limit: number;
+  }): Promise<Record<string, unknown>[]>;
+  /** Stable, unique tie-breaker column for keyset paging. Defaults to "id". */
+  idField?: string;
+}
+type SyncMode = "delta" | "full";
+interface ClivlySDK {
+  /**
+   * Build the `/clivly/auth/verify` handler the developer mounts in their app.
+   * Clivly's cloud calls it to validate a CRM user's identity against the host
+   * app's session. Pass a resolver that reads the host session from the request.
+   *
+   * The handler authenticates the caller against `config.verifyToken` (presented
+   * as `Authorization: Bearer <token>`) before invoking the resolver, so the
+   * endpoint can't be used by third parties to probe host sessions. It fails
+   * closed with HTTP 500 if `verifyToken` is unset.
+   */
+  createAuthVerifyHandler(resolveUser: (req: Request) => Promise<ClivlyUser | null> | ClivlyUser | null): (req: Request) => Promise<Response>;
+  /** Send a single heartbeat now. Returns true on success. */
+  heartbeat(): Promise<boolean>;
+  /** Connect: send the initial heartbeat and start the keep-alive loop. */
+  start(): Promise<void>;
+  /** Stop the keep-alive loop. */
+  stop(): void;
+  /**
+   * Sync all configured sources now. `delta` (default) pages changed rows since
+   * the last cursor; `full` pushes each complete entity so the server can
+   * reconcile leavers (archive-on-leave). Throws if a push fails, so callers see
+   * the failure — the background keep-alive loop swallows and retries instead.
+   */
+  sync(options?: {
+    mode?: SyncMode;
+  }): Promise<void>;
+}
+//#endregion
+//#region src/index.d.ts
+/**
+ * Create the Clivly SDK. The implemented surface — heartbeat/discovery reporting
+ * and the auth-verify handler — connects a developer's app to a running Clivly
+ * backend today. Tunnel management and CRM write-back are scaffolded (see the
+ * clearly-marked TODOs) and land with the Cloudflare infrastructure.
+ */
+declare function createClivlySDK(config: ClivlySDKConfig): ClivlySDK;
+//#endregion
+export { type ClivlySDK, type ClivlySDKConfig, type ClivlyUser, type DiscoveredTable, createClivlySDK };

package/dist/index.mjs

@@ -0,0 +1,286 @@
+//#region src/sync.ts
+const DEFAULT_ID_FIELD = "id";
+function isAfter(candidate, current) {
+	const ct = candidate.time.getTime();
+	const bt = current.time.getTime();
+	if (ct !== bt) return ct > bt;
+	return candidate.id > current.id;
+}
+function nextCursor(rows, cursorField, idField, current) {
+	let max = current;
+	for (const row of rows) {
+		const raw = row[cursorField];
+		if (raw === null || raw === void 0) continue;
+		const time = raw instanceof Date ? raw : new Date(String(raw));
+		if (Number.isNaN(time.getTime())) continue;
+		const idRaw = row[idField];
+		const candidate = {
+			time,
+			id: idRaw === null || idRaw === void 0 ? "" : String(idRaw)
+		};
+		if (!max || isAfter(candidate, max)) max = candidate;
+	}
+	return max;
+}
+async function syncSource(args) {
+	const { source, path, since, batchSize, push } = args;
+	const idField = source.idField ?? DEFAULT_ID_FIELD;
+	let cursor = since;
+	let pushed = 0;
+	for (;;) {
+		const rows = await source.fetchPage({
+			since: cursor,
+			limit: batchSize
+		});
+		if (rows.length === 0) break;
+		if (!await push(path, {
+			source: source.entity,
+			rows,
+			mode: "delta"
+		})) return {
+			pushed,
+			cursor,
+			ok: false
+		};
+		pushed += rows.length;
+		cursor = nextCursor(rows, source.cursorField, idField, cursor);
+		if (rows.length < batchSize) break;
+	}
+	return {
+		pushed,
+		cursor,
+		ok: true
+	};
+}
+async function fullSyncSource(args) {
+	const { source, path, batchSize, push } = args;
+	const idField = source.idField ?? DEFAULT_ID_FIELD;
+	const all = [];
+	let cursor = null;
+	for (;;) {
+		const rows = await source.fetchPage({
+			since: cursor,
+			limit: batchSize
+		});
+		if (rows.length === 0) break;
+		all.push(...rows);
+		const next = nextCursor(rows, source.cursorField, idField, cursor);
+		const stalled = next !== null && cursor !== null && next.time.getTime() === cursor.time.getTime() && next.id === cursor.id;
+		cursor = next;
+		if (rows.length < batchSize || stalled) break;
+	}
+	if (all.length === 0) return {
+		pushed: 0,
+		cursor: null,
+		ok: true
+	};
+	const ok = await push(path, {
+		source: source.entity,
+		rows: all,
+		mode: "full"
+	});
+	return {
+		pushed: ok ? all.length : 0,
+		cursor,
+		ok
+	};
+}
+//#endregion
+//#region src/index.ts
+const DEFAULT_API_URL = "https://api.clivly.com";
+const DEFAULT_HEARTBEAT_MS = 6e4;
+const DEFAULT_BATCH_SIZE = 500;
+const DEFAULT_MAX_ATTEMPTS = 3;
+const DEFAULT_BASE_DELAY_MS = 500;
+const RETRYABLE_STATUS_FLOOR = 500;
+const RATE_LIMITED_STATUS = 429;
+const SYNC_CONTACTS_PATH = "/clivly/sdk/sync/contacts";
+const SYNC_COMPANIES_PATH = "/clivly/sdk/sync/companies";
+const TRAILING_SLASH = /\/$/;
+const BEARER_PREFIX = /^Bearer\s+/i;
+function entitiesToTables(entities, byName) {
+	if (!entities) return;
+	for (const entity of Object.values(entities.entities)) {
+		const columns = byName.get(entity.source) ?? /* @__PURE__ */ new Set();
+		for (const sourceColumn of Object.values(entity.fields)) columns.add(sourceColumn);
+		byName.set(entity.source, columns);
+	}
+}
+function resolveContactEntity(config) {
+	if (config.contactEntity) return config.contactEntity;
+	for (const entity of Object.values(config.entities?.entities ?? {})) if (entity.concept === "contact") return entity.source;
+}
+function buildSchema(config) {
+	const byName = /* @__PURE__ */ new Map();
+	for (const table of config.schema ?? []) {
+		const columns = byName.get(table.name) ?? /* @__PURE__ */ new Set();
+		for (const column of table.columns) columns.add(column);
+		byName.set(table.name, columns);
+	}
+	entitiesToTables(config.entities, byName);
+	if (config.contactEntity && !byName.has(config.contactEntity)) byName.set(config.contactEntity, new Set(config.contactFields ?? []));
+	return [...byName].map(([name, columns]) => ({
+		name,
+		columns: [...columns]
+	}));
+}
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+function jsonResponse(body, status) {
+	return new Response(JSON.stringify(body), {
+		status,
+		headers: { "content-type": "application/json" }
+	});
+}
+function timingSafeEqual(a, b) {
+	if (a.length !== b.length) return false;
+	let mismatch = 0;
+	for (let i = 0; i < a.length; i++) mismatch += a.charCodeAt(i) === b.charCodeAt(i) ? 0 : 1;
+	return mismatch === 0;
+}
+function bearerToken(req) {
+	const header = req.headers.get("authorization");
+	if (!(header && BEARER_PREFIX.test(header))) return null;
+	return header.replace(BEARER_PREFIX, "").trim();
+}
+function isRetryableStatus(status) {
+	return status === RATE_LIMITED_STATUS || status >= RETRYABLE_STATUS_FLOOR;
+}
+function retryAfterMs(res) {
+	const header = res.headers.get("retry-after");
+	if (!header) return null;
+	const seconds = Number(header);
+	if (!Number.isNaN(seconds)) return Math.max(0, seconds * 1e3);
+	const date = Date.parse(header);
+	return Number.isNaN(date) ? null : Math.max(0, date - Date.now());
+}
+function createFetcher(retry) {
+	const maxAttempts = Math.max(1, retry?.maxAttempts ?? DEFAULT_MAX_ATTEMPTS);
+	const baseDelayMs = retry?.baseDelayMs ?? DEFAULT_BASE_DELAY_MS;
+	return async (url, init) => {
+		for (let attempt = 1;; attempt++) {
+			let res = null;
+			try {
+				res = await fetch(url, init);
+			} catch {
+				res = null;
+			}
+			if (!(res === null || isRetryableStatus(res.status)) || attempt >= maxAttempts) return res;
+			const backoff = baseDelayMs * 2 ** (attempt - 1) + Math.random() * baseDelayMs;
+			await sleep(res ? retryAfterMs(res) ?? backoff : backoff);
+		}
+	};
+}
+/**
+* Create the Clivly SDK. The implemented surface — heartbeat/discovery reporting
+* and the auth-verify handler — connects a developer's app to a running Clivly
+* backend today. Tunnel management and CRM write-back are scaffolded (see the
+* clearly-marked TODOs) and land with the Cloudflare infrastructure.
+*/
+function createClivlySDK(config) {
+	const apiUrl = (config.apiUrl ?? DEFAULT_API_URL).replace(TRAILING_SLASH, "");
+	const heartbeatIntervalMs = config.heartbeatIntervalMs ?? DEFAULT_HEARTBEAT_MS;
+	const syncIntervalMs = config.sync?.intervalMs ?? heartbeatIntervalMs;
+	const timers = {
+		heartbeat: null,
+		sync: null
+	};
+	const batchSize = config.sync?.batchSize ?? DEFAULT_BATCH_SIZE;
+	const cursors = /* @__PURE__ */ new Map();
+	const fetcher = createFetcher(config.retry);
+	const push = async (path, body) => {
+		return (await fetcher(`${apiUrl}${path}`, {
+			method: "POST",
+			headers: {
+				"content-type": "application/json",
+				authorization: `Bearer ${config.apiKey}`
+			},
+			body: JSON.stringify(body)
+		}))?.ok ?? false;
+	};
+	const syncOne = async (source, path, mode) => {
+		const result = mode === "full" ? await fullSyncSource({
+			source,
+			path,
+			batchSize,
+			push
+		}) : await syncSource({
+			source,
+			path,
+			since: cursors.get(source.entity) ?? null,
+			batchSize,
+			push
+		});
+		cursors.set(source.entity, result.cursor);
+		return result.ok;
+	};
+	const runSync = async (options) => {
+		if (!config.source) return;
+		const mode = options?.mode ?? "delta";
+		const failed = [];
+		if (config.source.companies) {
+			if (!await syncOne(config.source.companies, SYNC_COMPANIES_PATH, mode)) failed.push(config.source.companies.entity);
+		}
+		if (!await syncOne(config.source.contacts, SYNC_CONTACTS_PATH, mode)) failed.push(config.source.contacts.entity);
+		if (failed.length > 0) throw new Error(`Clivly sync: push failed for ${failed.join(", ")}`);
+	};
+	const heartbeat = async () => {
+		return (await fetcher(`${apiUrl}/clivly/sdk/heartbeat`, {
+			method: "POST",
+			headers: {
+				"content-type": "application/json",
+				authorization: `Bearer ${config.apiKey}`
+			},
+			body: JSON.stringify({
+				framework: config.framework,
+				orm: config.orm,
+				sdkVersion: config.sdkVersion,
+				contactEntity: resolveContactEntity(config),
+				namespaceReady: config.namespaceReady ?? false,
+				schema: buildSchema(config)
+			})
+		}))?.ok ?? false;
+	};
+	const start = async () => {
+		await heartbeat();
+		if (config.sync?.onBoot !== false) await runSync().catch(() => {});
+		if (!timers.heartbeat) {
+			timers.heartbeat = setInterval(() => {
+				heartbeat().catch(() => {});
+			}, heartbeatIntervalMs);
+			timers.heartbeat.unref?.();
+		}
+		if (!timers.sync && config.source) {
+			timers.sync = setInterval(() => {
+				runSync().catch(() => {});
+			}, syncIntervalMs);
+			timers.sync.unref?.();
+		}
+	};
+	const stop = () => {
+		if (timers.heartbeat) {
+			clearInterval(timers.heartbeat);
+			timers.heartbeat = null;
+		}
+		if (timers.sync) {
+			clearInterval(timers.sync);
+			timers.sync = null;
+		}
+	};
+	const createAuthVerifyHandler = (resolveUser) => async (req) => {
+		if (!config.verifyToken) return jsonResponse({ error: "verify token not configured" }, 500);
+		const token = bearerToken(req);
+		if (!(token && timingSafeEqual(token, config.verifyToken))) return jsonResponse({ error: "unauthorized" }, 401);
+		const user = await resolveUser(req);
+		if (!user) return jsonResponse({ error: "unauthorized" }, 401);
+		return jsonResponse(user, 200);
+	};
+	return {
+		start,
+		stop,
+		heartbeat,
+		sync: runSync,
+		createAuthVerifyHandler
+	};
+}
+//#endregion
+export { createClivlySDK };

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@clivly/sdk",
+  "version": "0.1.0",
+  "private": false,
+  "type": "module",
+  "description": "Clivly SDK — connect your app to Clivly Cloud (heartbeat, discovery, auth bridge).",
+  "license": "MIT",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@clivly/core": "0.1.0"
+  },
+  "devDependencies": {
+    "tsdown": "^0.21.9",
+    "typescript": "^6",
+    "vitest": "^3.2.0",
+    "@clivly.com/config": "0.0.0"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "check-types": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.mts"
+}