@clivly/sdk 0.1.0 → 0.2.0

package/dist/index.mjs

@@ -1,3 +1,87 @@
+import { t as DRIZZLE_META } from "./drizzle-meta-CAJ43cLc.mjs";
+//#region src/doctor.ts
+function configuredSources(config) {
+	const sources = [];
+	if (config.source?.contacts) sources.push(config.source.contacts);
+	if (config.source?.companies) sources.push(config.source.companies);
+	return sources;
+}
+/**
+* Run the six read-only setup checks and return a structured report. Every check
+* captures its own error into `detail` rather than throwing, so one failure never
+* hides the rest. `ok` is the AND of all non-skipped checks.
+*/
+async function runDoctor(args) {
+	const { config, connect } = args;
+	const checks = [];
+	const sources = configuredSources(config);
+	const hasKey = Boolean(config.apiKey);
+	checks.push({
+		name: "API key present",
+		ok: hasKey,
+		detail: hasKey ? "CLIVLY_API_KEY is set." : "apiKey is empty — set CLIVLY_API_KEY."
+	});
+	const entityCount = config.entities ? Object.keys(config.entities.entities).length : 0;
+	checks.push({
+		name: "Entities configured",
+		ok: entityCount > 0,
+		detail: entityCount > 0 ? `${entityCount} entit${entityCount === 1 ? "y" : "ies"} configured.` : "No `entities` config — pass defineClivlyConfig(...) as `entities`."
+	});
+	checks.push({
+		name: "Sources configured",
+		ok: sources.length > 0,
+		detail: sources.length > 0 ? `${sources.length} source(s) to mirror.` : "No `source.contacts` — nothing to sync."
+	});
+	for (const source of sources) {
+		const meta = source[DRIZZLE_META];
+		if (!meta) {
+			checks.push({
+				name: `Cursor/id columns exist (${source.entity})`,
+				ok: false,
+				skipped: true,
+				detail: `"${source.entity}" is a hand-written source — column check skipped.`
+			});
+			continue;
+		}
+		const idField = source.idField ?? "id";
+		const missing = [meta.cursorField, idField].filter((field) => !meta.columnKeys.includes(field));
+		checks.push({
+			name: `Cursor/id columns exist (${source.entity})`,
+			ok: missing.length === 0,
+			detail: missing.length === 0 ? `"${source.entity}": ${meta.cursorField} + ${idField} present.` : `"${source.entity}" missing column(s): ${missing.join(", ")}.`
+		});
+	}
+	for (const source of sources) try {
+		const rows = await source.fetchPage({
+			since: null,
+			limit: 1
+		});
+		const firstRow = rows[0];
+		const missingCursor = firstRow !== void 0 && !(source.cursorField in firstRow);
+		checks.push({
+			name: `Sample fetch (${source.entity})`,
+			ok: !missingCursor,
+			detail: missingCursor ? `"${source.entity}" rows lack the cursor key "${source.cursorField}".` : `"${source.entity}" returned ${rows.length} row(s).`
+		});
+	} catch (error) {
+		checks.push({
+			name: `Sample fetch (${source.entity})`,
+			ok: false,
+			detail: `"${source.entity}" fetchPage threw: ${error.message}`
+		});
+	}
+	const result = await connect();
+	checks.push({
+		name: "Heartbeat",
+		ok: result.ok,
+		detail: result.ok ? `Reached Clivly — org "${result.org?.name ?? "(unnamed)"}".` : `Could not connect (${result.reason}).`
+	});
+	return {
+		ok: checks.every((check) => check.skipped || check.ok),
+		checks
+	};
+}
+//#endregion
 //#region src/sync.ts
 const DEFAULT_ID_FIELD = "id";
 function isAfter(candidate, current) {
@@ -86,6 +170,42 @@ async function fullSyncSource(args) {
 	};
 }
 //#endregion
+//#region src/errors.ts
+var ClivlyError = class ClivlyError extends Error {
+	/** HTTP status, or null when the request never completed (network error). */
+	status;
+	reason;
+	/** Whether a retry could plausibly succeed (network, 429, 5xx). */
+	retryable;
+	constructor(result, message) {
+		super(message ?? `Clivly connection failed: ${result.reason}`);
+		this.name = new.target.name;
+		this.status = result.status;
+		this.reason = result.reason;
+		this.retryable = result.retryable;
+	}
+	/**
+	* Build the error subclass matching a failed result's reason, or `null` when
+	* the result is `ok`.
+	*/
+	static from(result) {
+		if (result.ok) return null;
+		switch (result.reason) {
+			case "invalid_api_key":
+			case "forbidden": return new ClivlyAuthError(result);
+			case "rate_limited": return new ClivlyRateLimitError(result);
+			case "network_error": return new ClivlyNetworkError(result);
+			default: return new ClivlyError(result);
+		}
+	}
+};
+/** The API key was rejected (401) or lacks access (403). Not retryable. */
+var ClivlyAuthError = class extends ClivlyError {};
+/** Rate limited (429). Retryable after backoff / `Retry-After`. */
+var ClivlyRateLimitError = class extends ClivlyError {};
+/** The request never reached the server (network/DNS/TLS). Retryable. */
+var ClivlyNetworkError = class extends ClivlyError {};
+//#endregion
 //#region src/index.ts
 const DEFAULT_API_URL = "https://api.clivly.com";
 const DEFAULT_HEARTBEAT_MS = 6e4;
@@ -125,6 +245,22 @@ function buildSchema(config) {
 	}));
 }
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+function createMemoryCursorStore() {
+	const cursors = /* @__PURE__ */ new Map();
+	return {
+		get: (entity) => cursors.get(entity) ?? null,
+		set: (entity, cursor) => {
+			cursors.set(entity, cursor);
+		}
+	};
+}
+function isLikelyServerless() {
+	const runtime = globalThis;
+	if (runtime.navigator?.userAgent === "Cloudflare-Workers") return true;
+	if (runtime.EdgeRuntime !== void 0) return true;
+	const env = runtime.process?.env;
+	return Boolean(env?.AWS_LAMBDA_FUNCTION_NAME || env?.VERCEL);
+}
 function jsonResponse(body, status) {
 	return new Response(JSON.stringify(body), {
 		status,
@@ -145,6 +281,25 @@ function bearerToken(req) {
 function isRetryableStatus(status) {
 	return status === RATE_LIMITED_STATUS || status >= RETRYABLE_STATUS_FLOOR;
 }
+const UNAUTHORIZED_STATUS = 401;
+const FORBIDDEN_STATUS = 403;
+const CLIENT_ERROR_FLOOR = 400;
+const SERVICE_UNAVAILABLE_STATUS = 503;
+function connectReason(status) {
+	if (status === UNAUTHORIZED_STATUS) return "invalid_api_key";
+	if (status === FORBIDDEN_STATUS) return "forbidden";
+	if (status === RATE_LIMITED_STATUS) return "rate_limited";
+	if (status >= RETRYABLE_STATUS_FLOOR) return "server_error";
+	if (status >= CLIENT_ERROR_FLOOR) return "client_error";
+	return "server_error";
+}
+async function resolveOrg(response) {
+	try {
+		return (await response.json())?.org;
+	} catch {
+		return;
+	}
+}
 function retryAfterMs(res) {
 	const header = res.headers.get("retry-after");
 	if (!header) return null;
@@ -185,7 +340,7 @@ function createClivlySDK(config) {
 		sync: null
 	};
 	const batchSize = config.sync?.batchSize ?? DEFAULT_BATCH_SIZE;
-	const cursors = /* @__PURE__ */ new Map();
+	const cursorStore = config.cursorStore ?? createMemoryCursorStore();
 	const fetcher = createFetcher(config.retry);
 	const push = async (path, body) => {
 		return (await fetcher(`${apiUrl}${path}`, {
@@ -198,6 +353,7 @@ function createClivlySDK(config) {
 		}))?.ok ?? false;
 	};
 	const syncOne = async (source, path, mode) => {
+		const since = mode === "full" ? null : await cursorStore.get(source.entity) ?? null;
 		const result = mode === "full" ? await fullSyncSource({
 			source,
 			path,
@@ -206,11 +362,11 @@ function createClivlySDK(config) {
 		}) : await syncSource({
 			source,
 			path,
-			since: cursors.get(source.entity) ?? null,
+			since,
 			batchSize,
 			push
 		});
-		cursors.set(source.entity, result.cursor);
+		await cursorStore.set(source.entity, result.cursor);
 		return result.ok;
 	};
 	const runSync = async (options) => {
@@ -223,24 +379,67 @@ function createClivlySDK(config) {
 		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 sendHeartbeat = () => 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)
+		})
+	});
 	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;
+		return (await sendHeartbeat())?.ok ?? false;
+	};
+	const connect = async () => {
+		const response = await sendHeartbeat();
+		if (response === null) return {
+			ok: false,
+			status: null,
+			reason: "network_error",
+			retryable: true
+		};
+		if (response.ok) return {
+			ok: true,
+			status: response.status,
+			reason: "ok",
+			retryable: false,
+			org: await resolveOrg(response)
+		};
+		return {
+			ok: false,
+			status: response.status,
+			reason: connectReason(response.status),
+			retryable: isRetryableStatus(response.status)
+		};
+	};
+	const doctor = () => runDoctor({
+		config,
+		connect
+	});
+	const runScheduled = async (options) => {
+		await heartbeat();
+		if (config.source) await runSync(options);
+	};
+	const createClivlyHandler = () => async (_req) => {
+		try {
+			await runScheduled();
+			return jsonResponse({ ok: true }, 200);
+		} catch (error) {
+			return jsonResponse({
+				ok: false,
+				error: error instanceof Error ? error.message : String(error)
+			}, 500);
+		}
 	};
 	const start = async () => {
+		if (isLikelyServerless()) console.warn("clivly.start() uses a setInterval keep-alive loop, which does not persist on serverless/edge runtimes — it will stop ticking after the first response. Call clivly.runScheduled() from a scheduled/cron trigger, or mount clivly.createClivlyHandler() at a route instead.");
 		await heartbeat();
 		if (config.sync?.onBoot !== false) await runSync().catch(() => {});
 		if (!timers.heartbeat) {
@@ -267,7 +466,7 @@ function createClivlySDK(config) {
 		}
 	};
 	const createAuthVerifyHandler = (resolveUser) => async (req) => {
-		if (!config.verifyToken) return jsonResponse({ error: "verify token not configured" }, 500);
+		if (!config.verifyToken) return jsonResponse({ error: "Clivly verifyToken is not configured on the host app" }, SERVICE_UNAVAILABLE_STATUS);
 		const token = bearerToken(req);
 		if (!(token && timingSafeEqual(token, config.verifyToken))) return jsonResponse({ error: "unauthorized" }, 401);
 		const user = await resolveUser(req);
@@ -278,9 +477,13 @@ function createClivlySDK(config) {
 		start,
 		stop,
 		heartbeat,
+		connect,
+		doctor,
+		runScheduled,
+		createClivlyHandler,
 		sync: runSync,
 		createAuthVerifyHandler
 	};
 }
 //#endregion
-export { createClivlySDK };
+export { ClivlyAuthError, ClivlyError, ClivlyNetworkError, ClivlyRateLimitError, createClivlySDK };

package/dist/types-B0aSxJ6V.d.cts

@@ -0,0 +1,224 @@
+import { ClivlyEntitiesConfig } from "@clivly/core";
+
+//#region src/drizzle-meta.d.ts
+declare const DRIZZLE_META: unique symbol;
+interface DrizzleSourceMeta {
+  /** Drizzle property keys of every column on the source table. */
+  columnKeys: string[];
+  cursorField: string;
+  idField: string;
+}
+//#endregion
+//#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[];
+  /**
+   * Where per-entity delta cursors are persisted between syncs. Defaults to an
+   * in-memory store (fine for a long-lived process). On serverless/edge, pass a
+   * store backed by your own KV/DB so a cold start resumes delta sync instead of
+   * re-paging the whole entity. See `CursorStore`.
+   */
+  cursorStore?: CursorStore;
+  /**
+   * 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;
+  /**
+   * 🚧 Not implemented in 0.1.x. Reserved options for tunnel mode and CRM
+   * write-back — they have NO effect yet and land with the Cloudflare
+   * infrastructure. Grouped under `experimental` so the stable config surface
+   * above is unambiguous; nothing here is part of the supported API.
+   */
+  experimental?: {
+    /** Cloudflare Tunnel token — reserved for tunnel mode. Not wired up yet. */tunnelToken?: string; /** CRM write-back target — reserved. Not wired up yet. */
+    writeBack?: {
+      enabled?: boolean; /** Only crm_* tables are ever accepted; this narrows further. */
+      tables?: string[];
+    };
+  };
+  /** 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;
+  };
+  /**
+   * 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 503).
+   */
+  verifyToken?: string;
+}
+interface ClivlyUser {
+  email: string;
+  id: string;
+  name?: string;
+}
+interface DoctorCheck {
+  /** Human-readable outcome — what passed, or why it failed. */
+  detail: string;
+  /** Short label, e.g. "API key present". */
+  name: string;
+  /** True when the check passed. Ignored when `skipped` is true. */
+  ok: boolean;
+  /** True when the check could not run (e.g. a hand-written source). */
+  skipped?: boolean;
+}
+interface DoctorReport {
+  checks: DoctorCheck[];
+  /** AND of every non-skipped check's `ok`. */
+  ok: boolean;
+}
+type ClivlyConnectReason = "ok" | "invalid_api_key" | "forbidden" | "rate_limited" | "server_error" | "client_error" | "network_error";
+interface ClivlyConnectResult {
+  ok: boolean;
+  /** Org resolved from a successful heartbeat, when the server returns it. */
+  org?: {
+    id?: string;
+    name?: string;
+  };
+  reason: ClivlyConnectReason;
+  /** Whether a retry could plausibly succeed (network, 429, 5xx). */
+  retryable: boolean;
+  /** HTTP status, or null when the request never completed (network error). */
+  status: number | null;
+}
+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;
+  /** Set by `fromDrizzle`; lets `doctor` introspect the backing table. */
+  [DRIZZLE_META]?: DrizzleSourceMeta;
+}
+type SyncMode = "delta" | "full";
+interface CursorStore {
+  get(entity: string): Promise<SyncCursor | null> | SyncCursor | null;
+  set(entity: string, cursor: SyncCursor | null): Promise<void> | void;
+}
+interface ClivlySDK {
+  /**
+   * Send a single heartbeat and report the outcome richly: `ok`, the HTTP
+   * `status` (null on network failure), a coarse `reason`, whether it's
+   * `retryable`, and the resolved `org` when the server returns it. Never throws
+   * — inspect the result, or turn a failure into an exception with
+   * `ClivlyError.from(result)`. Prefer this over `heartbeat()` for onboarding,
+   * health checks, and one-shot serverless calls.
+   */
+  connect(): Promise<ClivlyConnectResult>;
+  /**
+   * 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 503 if `verifyToken` is unset (a missing config value, not a
+   * server fault — so it won't trip the host's 5xx error alerting).
+   */
+  createAuthVerifyHandler(resolveUser: (req: Request) => Promise<ClivlyUser | null> | ClivlyUser | null): (req: Request) => Promise<Response>;
+  /**
+   * A fetch handler to mount at a route and drive from an external scheduler
+   * (Cloudflare Workers cron, an uptime ping, etc.). Each request runs one
+   * `runScheduled()` and returns JSON: 200 when the sync succeeded, 500 otherwise.
+   * The ergonomic serverless entry point alongside `runScheduled()`.
+   */
+  createClivlyHandler(): (req: Request) => Promise<Response>;
+  /** Validate this setup end-to-end (read-only) before the first sync. */
+  doctor(): Promise<DoctorReport>;
+  /**
+   * Send a single heartbeat now. Returns true on success. Kept for the keep-alive
+   * loop and back-compat; use `connect()` when you need the failure reason.
+   */
+  heartbeat(): Promise<boolean>;
+  /**
+   * One-shot heartbeat + a single sync, with no keep-alive timers. The correct
+   * entry point on serverless/edge (Workers, Vercel, Lambda), where `start()`'s
+   * `setInterval` loop can't persist between invocations — call this from a
+   * scheduled/cron trigger. Throws if a sync push fails (so the run is marked
+   * failed); heartbeat is best-effort.
+   */
+  runScheduled(options?: {
+    mode?: SyncMode;
+  }): Promise<void>;
+  /**
+   * Send the initial heartbeat and start the keep-alive loop. For long-lived
+   * hosts only — on serverless/edge the interval can't persist, so prefer
+   * `runScheduled()` / `createClivlyHandler()`. Emits a warning if a serverless
+   * runtime is detected.
+   */
+  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
+export { ClivlyUser as a, DoctorCheck as c, ClivlySDKConfig as i, DoctorReport as l, ClivlyConnectResult as n, CursorStore as o, ClivlySDK as r, DiscoveredTable as s, ClivlyConnectReason as t, SyncSource as u };