clivly 0.8.0 → 0.9.0

package/namespace-probe-Dsp5uNkS.d.mts

@@ -0,0 +1,381 @@
+import { a as ClivlyEntitiesConfig } from "./entity-config-C4Yf_fPj.mjs";
+//#region ../sdk/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;
+  /** Every unique key on the table, each as its DB column names. */
+  uniqueConstraints?: string[][];
+}
+//#endregion
+//#region ../sdk/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;
+  /**
+   * Every unique key on the table, each as its DB column names. Primary keys
+   * are included (a PK is a unique key). Absent on v1 hosts and for
+   * hand-declared tables — consumers must treat absence as "unknown", never
+   * as "no unique keys".
+   */
+  uniqueConstraints?: 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;
+  /**
+   * Environment to read platform variables from when discovering the public
+   * trigger URL. Defaults to `process.env`. Injectable so tests and non-Node
+   * runtimes can supply their own.
+   */
+  env?: Record<string, string | undefined>;
+  /**
+   * 🚧 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.
+     *
+     * Optional — leave it unset and the SDK discovers the URL itself, from the
+     * hosting platform's environment or from the first request the route
+     * serves. Set it only to pin an address the SDK can't infer.
+     */
+    url?: string;
+    /**
+     * Path where `createClivlyHandler()` is mounted, e.g. `/api/clivly/tick`.
+     * Written by `clivly init`. Combined with the origin detected from the
+     * hosting platform so the SDK can report a trigger URL on its very first
+     * heartbeat, before any request has arrived to observe.
+     */
+    path?: 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). No
+   * cloud consumer calls this endpoint yet — it is an inert primitive reserved for
+   * a future CRM/dashboard auth-passthrough.
+   */
+  verifyToken?: string;
+}
+interface ClivlyUser {
+  email: string;
+  id: string;
+  name?: string;
+}
+interface ChatWidgetVisitor {
+  email: string;
+  name: string;
+}
+interface ChatSessionRequestBody {
+  visitor: ChatWidgetVisitor;
+  visitorToken?: string | null;
+  widgetId: string;
+}
+interface CreateChatSessionHandlerOptions {
+  allowedOrigins?: string[];
+  apiKey: string;
+  apiUrl?: string;
+  fetchImpl?: typeof fetch;
+  /**
+   * Optional host-auth hook. When provided, it runs on the incoming browser
+   * request (session cookies intact) and, on a non-null `ClivlyUser`, the host
+   * vouches for that verified identity to Clivly Cloud. Absent/null/throwing =
+   * the visitor stays self-reported. Never fails the session.
+   */
+  resolveUser?: (req: Request) => Promise<ClivlyUser | null> | ClivlyUser | null;
+}
+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;
+  /**
+   * True when the setup works but carries a risk worth stating.
+   *
+   * Distinct from `ok: false`, which means "this is broken, fix it before you
+   * rely on it". A warning is for a configuration that will run and sync, yet
+   * behaves in a way the developer probably did not intend — the cursor check
+   * below is the motivating case: syncing from an `id` column succeeds, mirrors
+   * every insert, and silently never re-syncs an edited row.
+   *
+   * Warnings do not fail `doctor`. Reporting them as failures would train
+   * people to ignore a red ladder on a working setup, which is worse than not
+   * reporting them at all.
+   */
+  warn?: 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" | "server_too_old" | "network_error";
+interface ClivlyConnectResult {
+  /**
+   * When the org's app last heartbeated, or null if it never has. Set only by
+   * `ping()` — `connect()` IS a heartbeat, so the question is meaningless there.
+   */
+  appLastSeenAt?: string | null;
+  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>;
+  /**
+   * Read-only diagnostic probe. Proves the API key is valid and Clivly is
+   * reachable, and resolves the org — without reporting anything about the
+   * host app. Use this for `clivly status` and other diagnostics; use
+   * `connect()` only from the running app, which is entitled to report its
+   * own state.
+   */
+  ping(): Promise<ClivlyConnectResult>;
+  /**
+   * 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 ../sdk/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 { ClivlyConnectResult as a, ClivlyUser as c, DiscoveredTable as d, DoctorCheck as f, ClivlyConnectReason as i, CreateChatSessionHandlerOptions as l, SyncSource as m, ChatSessionRequestBody as n, ClivlySDK as o, DoctorReport as p, ChatWidgetVisitor as r, ClivlySDKConfig as s, NamespaceIntrospector as t, CursorStore as u };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clivly",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "private": false,
   "type": "module",
   "description": "Clivly CLI — scaffold a CRM into your app (clivly init).",