@clivly/sdk 0.1.0 → 0.3.0-next.1

package/dist/namespace-probe-DFpvfl7T.d.mts

@@ -0,0 +1,299 @@
+import { ClivlyEntitiesConfig } from "@clivly/core";
+
+//#region src/drizzle-meta.d.ts
+declare const DRIZZLE_META: "__clivly_drizzle_source_meta__";
+interface DrizzleSourceMeta {
+  /** Drizzle property keys of every column on the source table. */
+  columnKeys: string[];
+  /** Schema-v2 typed column metadata derived from the Drizzle table. */
+  columnsMeta?: DiscoveredColumn[];
+  cursorField: string;
+  idField: string;
+  /** The backing table's real name, so discovery can key metadata by table. */
+  tableName?: string;
+}
+//#endregion
+//#region src/types.d.ts
+interface DiscoveredColumn {
+  isForeignKey?: boolean;
+  isPrimaryKey?: boolean;
+  name: string;
+  nullable?: boolean;
+  /** The column this FK points at, when it is a foreign key. */
+  references?: {
+    table: string;
+    column: string;
+  };
+  /** SQL/driver type, e.g. "text", "integer", "timestamp". */
+  type?: string;
+}
+interface DiscoveredTable {
+  columns: string[];
+  /** Schema-v2 typed column metadata (types, PK/FK, nullability). */
+  columnsMeta?: DiscoveredColumn[];
+  name: string;
+  /** Approximate source row count, when cheaply derivable. */
+  rowCount?: number;
+}
+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;
+  /**
+   * Optional live namespace probe, used on-demand by `doctor()`'s "Namespace
+   * reachable" check to verify every required source table + column is
+   * genuinely reachable. Not consulted by the heartbeat. Build one with
+   * `drizzleIntrospector(db)` from `@clivly/sdk/drizzle`.
+   */
+  introspector?: NamespaceIntrospector;
+  /**
+   * Self-reported readiness sent on every heartbeat as-is (no live check).
+   * For a real reachability check, configure `introspector` and run
+   * `doctor()`.
+   */
+  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;
+    deals?: SyncSource; /** Org-defined custom objects to mirror. Each carries its object-type slug. */
+    custom?: Array<SyncSource & {
+      objectType: string;
+    }>;
+  };
+  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;
+  };
+  /**
+   * The remote sync trigger: how Clivly Cloud asks this app to run a sync.
+   *
+   * Without it, cloud mode is push-only — Clivly can watch the app but can't
+   * start anything, so the dashboard's "Run sync" has nothing to call. With it,
+   * the SDK reports `url` on each heartbeat and requires every trigger request to
+   * be signed with `secret`.
+   */
+  syncTrigger?: {
+    /**
+     * Public URL of the route where `createClivlyHandler()` is mounted, e.g.
+     * `https://app.example.com/api/clivly/tick`. Reported to Clivly on each
+     * heartbeat; a URL set in the dashboard overrides it.
+     */
+    url?: string;
+    /**
+     * Signing secret (`whsec_…`) issued by Clivly under Integrations → Remote
+     * sync. When set, `createClivlyHandler()` rejects any request that isn't
+     * validly signed. Leave unset only if the route is already unreachable from
+     * the public internet.
+     */
+    secret?: 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 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. Each request runs one `runScheduled()`
+   * and returns JSON: 200 when the sync succeeded, 500 otherwise.
+   *
+   * Two callers use it: Clivly Cloud (when someone clicks "Run sync" — those
+   * requests are HMAC-signed and carry a run id), and the host's own scheduler
+   * (Workers cron, an uptime ping — no body).
+   *
+   * When `syncTrigger.secret` is set the handler rejects unsigned or
+   * badly-signed requests with 401. When it isn't, the route stays open to
+   * anyone who can reach it — set a secret if it's publicly routable.
+   */
+  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;
+    runId?: string;
+  }): 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;
+    runId?: string;
+  }): Promise<void>;
+}
+//#endregion
+//#region src/namespace-probe.d.ts
+interface NamespaceIntrospector {
+  /** All base table names in the reachable schema. */
+  listTables(): Promise<string[]>;
+  /** Prove a table is genuinely selectable (SELECT ... LIMIT 1). Throws if unreachable/denied. */
+  sampleSelect(table: string): Promise<void>;
+}
+//#endregion
+export { ClivlySDKConfig as a, DiscoveredTable as c, SyncSource as d, ClivlySDK as i, DoctorCheck as l, ClivlyConnectReason as n, ClivlyUser as o, ClivlyConnectResult as r, CursorStore as s, NamespaceIntrospector as t, DoctorReport as u };

package/dist/namespace-probe-DIBgCQca.d.cts

@@ -0,0 +1,299 @@
+import { ClivlyEntitiesConfig } from "@clivly/core";
+
+//#region src/drizzle-meta.d.ts
+declare const DRIZZLE_META: "__clivly_drizzle_source_meta__";
+interface DrizzleSourceMeta {
+  /** Drizzle property keys of every column on the source table. */
+  columnKeys: string[];
+  /** Schema-v2 typed column metadata derived from the Drizzle table. */
+  columnsMeta?: DiscoveredColumn[];
+  cursorField: string;
+  idField: string;
+  /** The backing table's real name, so discovery can key metadata by table. */
+  tableName?: string;
+}
+//#endregion
+//#region src/types.d.ts
+interface DiscoveredColumn {
+  isForeignKey?: boolean;
+  isPrimaryKey?: boolean;
+  name: string;
+  nullable?: boolean;
+  /** The column this FK points at, when it is a foreign key. */
+  references?: {
+    table: string;
+    column: string;
+  };
+  /** SQL/driver type, e.g. "text", "integer", "timestamp". */
+  type?: string;
+}
+interface DiscoveredTable {
+  columns: string[];
+  /** Schema-v2 typed column metadata (types, PK/FK, nullability). */
+  columnsMeta?: DiscoveredColumn[];
+  name: string;
+  /** Approximate source row count, when cheaply derivable. */
+  rowCount?: number;
+}
+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;
+  /**
+   * Optional live namespace probe, used on-demand by `doctor()`'s "Namespace
+   * reachable" check to verify every required source table + column is
+   * genuinely reachable. Not consulted by the heartbeat. Build one with
+   * `drizzleIntrospector(db)` from `@clivly/sdk/drizzle`.
+   */
+  introspector?: NamespaceIntrospector;
+  /**
+   * Self-reported readiness sent on every heartbeat as-is (no live check).
+   * For a real reachability check, configure `introspector` and run
+   * `doctor()`.
+   */
+  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;
+    deals?: SyncSource; /** Org-defined custom objects to mirror. Each carries its object-type slug. */
+    custom?: Array<SyncSource & {
+      objectType: string;
+    }>;
+  };
+  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;
+  };
+  /**
+   * The remote sync trigger: how Clivly Cloud asks this app to run a sync.
+   *
+   * Without it, cloud mode is push-only — Clivly can watch the app but can't
+   * start anything, so the dashboard's "Run sync" has nothing to call. With it,
+   * the SDK reports `url` on each heartbeat and requires every trigger request to
+   * be signed with `secret`.
+   */
+  syncTrigger?: {
+    /**
+     * Public URL of the route where `createClivlyHandler()` is mounted, e.g.
+     * `https://app.example.com/api/clivly/tick`. Reported to Clivly on each
+     * heartbeat; a URL set in the dashboard overrides it.
+     */
+    url?: string;
+    /**
+     * Signing secret (`whsec_…`) issued by Clivly under Integrations → Remote
+     * sync. When set, `createClivlyHandler()` rejects any request that isn't
+     * validly signed. Leave unset only if the route is already unreachable from
+     * the public internet.
+     */
+    secret?: 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 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. Each request runs one `runScheduled()`
+   * and returns JSON: 200 when the sync succeeded, 500 otherwise.
+   *
+   * Two callers use it: Clivly Cloud (when someone clicks "Run sync" — those
+   * requests are HMAC-signed and carry a run id), and the host's own scheduler
+   * (Workers cron, an uptime ping — no body).
+   *
+   * When `syncTrigger.secret` is set the handler rejects unsigned or
+   * badly-signed requests with 401. When it isn't, the route stays open to
+   * anyone who can reach it — set a secret if it's publicly routable.
+   */
+  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;
+    runId?: string;
+  }): 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;
+    runId?: string;
+  }): Promise<void>;
+}
+//#endregion
+//#region src/namespace-probe.d.ts
+interface NamespaceIntrospector {
+  /** All base table names in the reachable schema. */
+  listTables(): Promise<string[]>;
+  /** Prove a table is genuinely selectable (SELECT ... LIMIT 1). Throws if unreachable/denied. */
+  sampleSelect(table: string): Promise<void>;
+}
+//#endregion
+export { ClivlySDKConfig as a, DiscoveredTable as c, SyncSource as d, ClivlySDK as i, DoctorCheck as l, ClivlyConnectReason as n, ClivlyUser as o, ClivlyConnectResult as r, CursorStore as s, NamespaceIntrospector as t, DoctorReport as u };

package/dist/vite.cjs

@@ -0,0 +1,38 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region src/vite.ts
+/**
+* Vite dev-server plugin that runs the Clivly SDK lifecycle for you: on server
+* boot it calls `sdk.connect()` (for a clear status line) then `sdk.start()`
+* (the heartbeat + sync keep-alive loop), and calls `sdk.stop()` when the dev
+* server closes. Dev-only (`apply: "serve"`) — `start()`'s setInterval loop
+* does not persist on serverless/edge builds, so production on Workers/Lambda
+* should mount `sdk.createClivlyHandler()` and drive it from a cron trigger
+* instead. See docs/guides/connecting-to-clivly-cloud.md.
+*
+* Vite is an optional peer dependency imported type-only (`import type`), so
+* the built bundle carries no runtime dependency on Vite.
+*/
+function clivlyVite(sdk, options = {}) {
+	const label = options.name ?? "clivly";
+	return {
+		name: "clivly",
+		apply: "serve",
+		configureServer(server) {
+			const { logger } = server.config;
+			const boot = async () => {
+				const result = await sdk.connect();
+				if (result.ok) {
+					const org = result.org?.name ?? result.org?.id;
+					logger.info(`${label}: connected${org ? ` to ${org}` : ""}`);
+				} else logger.warn(`${label}: not connected (${result.reason})`);
+				await sdk.start();
+			};
+			boot().catch((error) => {
+				logger.error(`${label}: startup failed — ${error instanceof Error ? error.message : String(error)}`);
+			});
+			server.httpServer?.once("close", () => sdk.stop());
+		}
+	};
+}
+//#endregion
+exports.clivlyVite = clivlyVite;

package/dist/vite.d.cts

@@ -0,0 +1,23 @@
+import { i as ClivlySDK } from "./namespace-probe-DIBgCQca.cjs";
+import { Plugin } from "vite";
+
+//#region src/vite.d.ts
+interface ClivlyViteOptions {
+  /** Log prefix for Clivly's boot lines. Defaults to "clivly". */
+  name?: string;
+}
+/**
+ * Vite dev-server plugin that runs the Clivly SDK lifecycle for you: on server
+ * boot it calls `sdk.connect()` (for a clear status line) then `sdk.start()`
+ * (the heartbeat + sync keep-alive loop), and calls `sdk.stop()` when the dev
+ * server closes. Dev-only (`apply: "serve"`) — `start()`'s setInterval loop
+ * does not persist on serverless/edge builds, so production on Workers/Lambda
+ * should mount `sdk.createClivlyHandler()` and drive it from a cron trigger
+ * instead. See docs/guides/connecting-to-clivly-cloud.md.
+ *
+ * Vite is an optional peer dependency imported type-only (`import type`), so
+ * the built bundle carries no runtime dependency on Vite.
+ */
+declare function clivlyVite(sdk: ClivlySDK, options?: ClivlyViteOptions): Plugin;
+//#endregion
+export { ClivlyViteOptions, clivlyVite };

package/dist/vite.d.mts

@@ -0,0 +1,23 @@
+import { i as ClivlySDK } from "./namespace-probe-DFpvfl7T.mjs";
+import { Plugin } from "vite";
+
+//#region src/vite.d.ts
+interface ClivlyViteOptions {
+  /** Log prefix for Clivly's boot lines. Defaults to "clivly". */
+  name?: string;
+}
+/**
+ * Vite dev-server plugin that runs the Clivly SDK lifecycle for you: on server
+ * boot it calls `sdk.connect()` (for a clear status line) then `sdk.start()`
+ * (the heartbeat + sync keep-alive loop), and calls `sdk.stop()` when the dev
+ * server closes. Dev-only (`apply: "serve"`) — `start()`'s setInterval loop
+ * does not persist on serverless/edge builds, so production on Workers/Lambda
+ * should mount `sdk.createClivlyHandler()` and drive it from a cron trigger
+ * instead. See docs/guides/connecting-to-clivly-cloud.md.
+ *
+ * Vite is an optional peer dependency imported type-only (`import type`), so
+ * the built bundle carries no runtime dependency on Vite.
+ */
+declare function clivlyVite(sdk: ClivlySDK, options?: ClivlyViteOptions): Plugin;
+//#endregion
+export { ClivlyViteOptions, clivlyVite };