@clivly/sdk 0.1.0 → 0.2.0

package/dist/types-DWt-ytBQ.d.mts

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clivly/sdk",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "private": false,
   "type": "module",
   "description": "Clivly SDK — connect your app to Clivly Cloud (heartbeat, discovery, auth bridge).",
@@ -8,8 +8,24 @@
   "sideEffects": false,
   "exports": {
     ".": {
-      "types": "./dist/index.d.mts",
-      "import": "./dist/index.mjs"
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./drizzle": {
+      "import": {
+        "types": "./dist/drizzle.d.mts",
+        "default": "./dist/drizzle.mjs"
+      },
+      "require": {
+        "types": "./dist/drizzle.d.cts",
+        "default": "./dist/drizzle.cjs"
+      }
     }
   },
   "files": [
@@ -19,19 +35,29 @@
     "access": "public"
   },
   "dependencies": {
-    "@clivly/core": "0.1.0"
+    "@clivly/core": "0.2.0"
+  },
+  "peerDependencies": {
+    "drizzle-orm": ">=0.30"
+  },
+  "peerDependenciesMeta": {
+    "drizzle-orm": {
+      "optional": true
+    }
   },
   "devDependencies": {
+    "@electric-sql/pglite": "^0.5.4",
+    "drizzle-orm": "^0.45.2",
     "tsdown": "^0.21.9",
     "typescript": "^6",
-    "vitest": "^3.2.0",
-    "@clivly.com/config": "0.0.0"
+    "vitest": "^3.2.0"
   },
   "scripts": {
     "build": "tsdown",
     "check-types": "tsc --noEmit",
     "test": "vitest run"
   },
-  "main": "./dist/index.mjs",
-  "types": "./dist/index.d.mts"
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.cts"
 }