clivly 0.2.0 → 0.2.2

package/mappings-config-DTu_2cyx.cjs

@@ -0,0 +1,104 @@
+const require_entity_config = require("./entity-config-Cvjo1cpv.cjs");
+//#region ../core/src/mappings-config.ts
+const RESERVED_FIELD = "id";
+/**
+* Restrict a persisted field map to what the mirror can actually store: drop
+* the reserved `id` key (for every concept) and, for materialized concepts
+* (contact/company), any key that isn't canonical. This makes the pipeline
+* resilient to legacy or mis-suggested field maps — a stray `id` no longer
+* blocks the whole sync.
+*/
+function canonicalFields(concept, fieldMap) {
+	const allowed = require_entity_config.CANONICAL_FIELDS[concept];
+	const result = {};
+	for (const [field, column] of Object.entries(fieldMap)) {
+		if (field === RESERVED_FIELD) continue;
+		if (allowed && !allowed.includes(field)) continue;
+		result[field] = column;
+	}
+	return result;
+}
+const DEFAULT_ROLE = "primary";
+const ACTIVE_STATUS = "active";
+function isEligible(row) {
+	return (row.status ?? ACTIVE_STATUS) === ACTIVE_STATUS && Object.keys(row.fieldMap ?? {}).length > 0;
+}
+/**
+* Preferred key for a row: the bare source table when it backs a single entity,
+* else role-suffixed so multiple roles on one table stay distinct and stable
+* (the primary role keeps the bare name). Uniqueness is still enforced by the
+* caller in case two rows land on the same preferred key.
+*/
+function preferredKey(row, tableCounts) {
+	const role = row.role ?? DEFAULT_ROLE;
+	if ((tableCounts.get(row.sourceTable) ?? 0) <= 1) return row.sourceTable;
+	return role === DEFAULT_ROLE ? row.sourceTable : `${row.sourceTable}__${role}`;
+}
+function uniquify(base, used) {
+	if (!used.has(base)) {
+		used.add(base);
+		return base;
+	}
+	let suffix = 2;
+	while (used.has(`${base}__${suffix}`)) suffix++;
+	const key = `${base}__${suffix}`;
+	used.add(key);
+	return key;
+}
+function buildEntity(row, refIndex) {
+	const entity = {
+		concept: row.targetConcept,
+		source: row.sourceTable,
+		role: row.role ?? DEFAULT_ROLE,
+		fields: canonicalFields(row.targetConcept, row.fieldMap)
+	};
+	if (row.targetConcept === "custom" && row.targetObjectTypeId) entity.targetObjectTypeId = row.targetObjectTypeId;
+	if (row.filter && Object.keys(row.filter).length > 0) entity.filter = row.filter;
+	if (row.relationships && Object.keys(row.relationships).length > 0) {
+		const relationships = {};
+		for (const [name, spec] of Object.entries(row.relationships)) {
+			const rel = spec;
+			relationships[name] = {
+				entity: refIndex.get(rel.entity) ?? rel.entity,
+				via: rel.via
+			};
+		}
+		entity.relationships = relationships;
+	}
+	return entity;
+}
+/**
+* Compile persisted mapping rows into a `ClivlyEntitiesConfig`. Only `active`
+* rows with at least one mapped field are included; disabled/suggested rows and
+* unmapped rows are skipped. Returns `{ entities: {} }` when nothing is
+* eligible — a no-op the view compiler and sync engine both tolerate.
+*/
+function mappingsToEntitiesConfig(rows) {
+	const eligible = rows.filter(isEligible);
+	const tableCounts = /* @__PURE__ */ new Map();
+	for (const row of eligible) tableCounts.set(row.sourceTable, (tableCounts.get(row.sourceTable) ?? 0) + 1);
+	const used = /* @__PURE__ */ new Set();
+	const tableAnchor = /* @__PURE__ */ new Map();
+	const assigned = [];
+	for (const row of eligible) {
+		const key = uniquify(preferredKey(row, tableCounts), used);
+		assigned.push({
+			row,
+			key
+		});
+		if ((row.role ?? DEFAULT_ROLE) === DEFAULT_ROLE || !tableAnchor.has(row.sourceTable)) tableAnchor.set(row.sourceTable, key);
+	}
+	const refIndex = /* @__PURE__ */ new Map();
+	for (const { key } of assigned) refIndex.set(key, key);
+	for (const [table, key] of tableAnchor) if (!refIndex.has(table)) refIndex.set(table, key);
+	const entities = {};
+	for (const { row, key } of assigned) entities[key] = buildEntity(row, refIndex);
+	return { entities };
+}
+//#endregion
+Object.defineProperty(exports, "mappingsToEntitiesConfig", {
+	enumerable: true,
+	get: function() {
+		return mappingsToEntitiesConfig;
+	}
+});

package/mappings-config-DjRLCb2Q.d.cts

@@ -0,0 +1,42 @@
+import { a as ClivlyEntitiesConfig } from "./entity-config-GczjD3y8.cjs";
+
+//#region ../core/src/mappings-config.d.ts
+/**
+ * Mappings → Entity Config bridge.
+ *
+ * `crm_entity_mappings` rows are the single source of truth for how a host
+ * schema maps onto Clivly's CRM concepts. This module compiles those rows into
+ * a `ClivlyEntitiesConfig` — the contract the view compiler and sync engine
+ * consume — so the persisted mapping and the runtime pipeline never diverge.
+ *
+ * The row model has no explicit entity-key column (it's keyed by
+ * `sourceTable + targetConcept + role`), but the config's `relationships`
+ * reference other entities *by key*. This builder therefore derives a stable
+ * key per row and resolves each relationship's `entity` reference through the
+ * same derivation — so a relationship stored as `entity: "<relatedTable>"`
+ * (the shape `mappings.suggest` produces) resolves to the right entity.
+ */
+/**
+ * A persisted `crm_entity_mappings` row, narrowed to the columns the builder
+ * reads. Structurally compatible with the Drizzle row (jsonb columns typed
+ * loosely) so the API layer can pass `db.select()` results straight in.
+ */
+interface EntityMappingRow {
+  fieldMap: Record<string, string>;
+  filter?: Record<string, unknown> | null;
+  relationships?: Record<string, unknown> | null;
+  role?: string | null;
+  sourceTable: string;
+  status?: string | null;
+  targetConcept: string;
+  targetObjectTypeId?: string | null;
+}
+/**
+ * Compile persisted mapping rows into a `ClivlyEntitiesConfig`. Only `active`
+ * rows with at least one mapped field are included; disabled/suggested rows and
+ * unmapped rows are skipped. Returns `{ entities: {} }` when nothing is
+ * eligible — a no-op the view compiler and sync engine both tolerate.
+ */
+declare function mappingsToEntitiesConfig(rows: EntityMappingRow[]): ClivlyEntitiesConfig;
+//#endregion
+export { mappingsToEntitiesConfig as n, EntityMappingRow as t };

package/mappings-config-GxiYsSBQ.d.mts

@@ -0,0 +1,42 @@
+import { a as ClivlyEntitiesConfig } from "./entity-config-D1DFyeUp.mjs";
+
+//#region ../core/src/mappings-config.d.ts
+/**
+ * Mappings → Entity Config bridge.
+ *
+ * `crm_entity_mappings` rows are the single source of truth for how a host
+ * schema maps onto Clivly's CRM concepts. This module compiles those rows into
+ * a `ClivlyEntitiesConfig` — the contract the view compiler and sync engine
+ * consume — so the persisted mapping and the runtime pipeline never diverge.
+ *
+ * The row model has no explicit entity-key column (it's keyed by
+ * `sourceTable + targetConcept + role`), but the config's `relationships`
+ * reference other entities *by key*. This builder therefore derives a stable
+ * key per row and resolves each relationship's `entity` reference through the
+ * same derivation — so a relationship stored as `entity: "<relatedTable>"`
+ * (the shape `mappings.suggest` produces) resolves to the right entity.
+ */
+/**
+ * A persisted `crm_entity_mappings` row, narrowed to the columns the builder
+ * reads. Structurally compatible with the Drizzle row (jsonb columns typed
+ * loosely) so the API layer can pass `db.select()` results straight in.
+ */
+interface EntityMappingRow {
+  fieldMap: Record<string, string>;
+  filter?: Record<string, unknown> | null;
+  relationships?: Record<string, unknown> | null;
+  role?: string | null;
+  sourceTable: string;
+  status?: string | null;
+  targetConcept: string;
+  targetObjectTypeId?: string | null;
+}
+/**
+ * Compile persisted mapping rows into a `ClivlyEntitiesConfig`. Only `active`
+ * rows with at least one mapped field are included; disabled/suggested rows and
+ * unmapped rows are skipped. Returns `{ entities: {} }` when nothing is
+ * eligible — a no-op the view compiler and sync engine both tolerate.
+ */
+declare function mappingsToEntitiesConfig(rows: EntityMappingRow[]): ClivlyEntitiesConfig;
+//#endregion
+export { mappingsToEntitiesConfig as n, EntityMappingRow as t };

package/namespace-probe-BtS0nXcr.d.cts

@@ -0,0 +1,299 @@
+import { a as ClivlyEntitiesConfig } from "./entity-config-GczjD3y8.cjs";
+
+//#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;
+}
+//#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;
+}
+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 ../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 { 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 };