@clivly/core 0.8.0 → 0.9.0

package/dist/integration-state.d.cts

@@ -0,0 +1,88 @@
+//#region src/integration-state.d.ts
+declare const INTEGRATION_STEPS: readonly ["credential", "application", "schema", "mapping", "trigger", "sync", "widget"];
+type StepId = (typeof INTEGRATION_STEPS)[number];
+/** `blocked` means "prerequisite unmet", never "broken" — see C-19. */
+type StepState = "done" | "active" | "blocked" | "failed" | "skipped";
+type IntegrationStatus = "not_configured" | "sdk_installed" | "awaiting_connection" | "connected" | "schema_discovered" | "mapping_required" | "trigger_required" | "ready_to_sync" | "syncing" | "healthy" | "warning" | "error" | "disconnected";
+declare const INTEGRATION_STEP_LABELS: Record<StepId, string>;
+/** Each step's prerequisites. Ordering is enforced by a test, not convention. */
+declare const STEP_PREREQUISITES: Record<StepId, readonly StepId[]>;
+declare function stepIndex(id: StepId): number;
+interface RunFact {
+  at: number;
+  message?: string;
+  ok: boolean;
+}
+interface IntegrationFacts {
+  discoveredTableCount: number;
+  /**
+   * Has this app ever checked in? Distinguishes "never installed" from "was
+   * working, now silent" — the same absent heartbeat means different things,
+   * and only one of them is diagnosed rather than set up.
+   */
+  everConnected: boolean;
+  hasCredential: boolean;
+  lastHeartbeatAt: number | null;
+  lastRun: RunFact | null;
+  mappedEntityCount: number;
+  now: number;
+  syncInFlight: boolean;
+  /** A trigger URL and secret both exist, so Clivly can ask the app to sync. */
+  triggerConfigured: boolean;
+  warnings: string[];
+  widgetInstalled: boolean;
+}
+interface StepProblem {
+  code: string;
+  fix: string;
+  message: string;
+}
+interface IntegrationStep {
+  blockedBy: StepId | null;
+  evidence: string | null;
+  id: StepId;
+  label: string;
+  problem: StepProblem | null;
+  state: StepState;
+}
+declare function formatAge(ms: number): string;
+/**
+ * Walk the ladder once. A step is `blocked` when an earlier step it needs has
+ * not been satisfied — a prerequisite statement, not a verdict about this step
+ * — and only the first unsatisfied step is `active`, so exactly one root cause
+ * ever surfaces.
+ */
+declare function resolveSteps(facts: IntegrationFacts): IntegrationStep[];
+/**
+ * Collapse the ladder to the single status the surfaces switch on. Live
+ * conditions — a run in flight, a failure, a heartbeat gone quiet — win over
+ * ladder position, because they describe the integration as it is now rather
+ * than how far setup once got.
+ */
+declare function deriveStatus(steps: IntegrationStep[], facts: IntegrationFacts): IntegrationStatus;
+interface NextAction {
+  command: string | null;
+  envFile: string | null;
+  label: string;
+}
+interface IntegrationState {
+  next: NextAction | null;
+  status: IntegrationStatus;
+  steps: IntegrationStep[];
+}
+/**
+ * The command that installs Clivly into a host app. Exported because the connect
+ * dialog prints it too, and it must be the same string as the one the ladder
+ * recommends — that pairing is what C-05 broke.
+ */
+declare const INSTALL_COMMAND = "npx clivly init";
+/**
+ * THE one producer of `next.command`. Six surfaces previously each invented
+ * their own "run this next" string, and one of them named a read-only command
+ * as the fix for a write problem (C-05). If you need a command for the
+ * next-action slot, call this — do not write another one.
+ */
+declare function nextAction(steps: IntegrationStep[], status: IntegrationStatus): NextAction | null;
+declare function computeIntegrationState(facts: IntegrationFacts): IntegrationState;
+//#endregion
+export { INSTALL_COMMAND, INTEGRATION_STEPS, INTEGRATION_STEP_LABELS, IntegrationFacts, IntegrationState, IntegrationStatus, IntegrationStep, NextAction, RunFact, STEP_PREREQUISITES, StepId, StepProblem, StepState, computeIntegrationState, deriveStatus, formatAge, nextAction, resolveSteps, stepIndex };

package/dist/integration-state.d.mts

@@ -0,0 +1,88 @@
+//#region src/integration-state.d.ts
+declare const INTEGRATION_STEPS: readonly ["credential", "application", "schema", "mapping", "trigger", "sync", "widget"];
+type StepId = (typeof INTEGRATION_STEPS)[number];
+/** `blocked` means "prerequisite unmet", never "broken" — see C-19. */
+type StepState = "done" | "active" | "blocked" | "failed" | "skipped";
+type IntegrationStatus = "not_configured" | "sdk_installed" | "awaiting_connection" | "connected" | "schema_discovered" | "mapping_required" | "trigger_required" | "ready_to_sync" | "syncing" | "healthy" | "warning" | "error" | "disconnected";
+declare const INTEGRATION_STEP_LABELS: Record<StepId, string>;
+/** Each step's prerequisites. Ordering is enforced by a test, not convention. */
+declare const STEP_PREREQUISITES: Record<StepId, readonly StepId[]>;
+declare function stepIndex(id: StepId): number;
+interface RunFact {
+  at: number;
+  message?: string;
+  ok: boolean;
+}
+interface IntegrationFacts {
+  discoveredTableCount: number;
+  /**
+   * Has this app ever checked in? Distinguishes "never installed" from "was
+   * working, now silent" — the same absent heartbeat means different things,
+   * and only one of them is diagnosed rather than set up.
+   */
+  everConnected: boolean;
+  hasCredential: boolean;
+  lastHeartbeatAt: number | null;
+  lastRun: RunFact | null;
+  mappedEntityCount: number;
+  now: number;
+  syncInFlight: boolean;
+  /** A trigger URL and secret both exist, so Clivly can ask the app to sync. */
+  triggerConfigured: boolean;
+  warnings: string[];
+  widgetInstalled: boolean;
+}
+interface StepProblem {
+  code: string;
+  fix: string;
+  message: string;
+}
+interface IntegrationStep {
+  blockedBy: StepId | null;
+  evidence: string | null;
+  id: StepId;
+  label: string;
+  problem: StepProblem | null;
+  state: StepState;
+}
+declare function formatAge(ms: number): string;
+/**
+ * Walk the ladder once. A step is `blocked` when an earlier step it needs has
+ * not been satisfied — a prerequisite statement, not a verdict about this step
+ * — and only the first unsatisfied step is `active`, so exactly one root cause
+ * ever surfaces.
+ */
+declare function resolveSteps(facts: IntegrationFacts): IntegrationStep[];
+/**
+ * Collapse the ladder to the single status the surfaces switch on. Live
+ * conditions — a run in flight, a failure, a heartbeat gone quiet — win over
+ * ladder position, because they describe the integration as it is now rather
+ * than how far setup once got.
+ */
+declare function deriveStatus(steps: IntegrationStep[], facts: IntegrationFacts): IntegrationStatus;
+interface NextAction {
+  command: string | null;
+  envFile: string | null;
+  label: string;
+}
+interface IntegrationState {
+  next: NextAction | null;
+  status: IntegrationStatus;
+  steps: IntegrationStep[];
+}
+/**
+ * The command that installs Clivly into a host app. Exported because the connect
+ * dialog prints it too, and it must be the same string as the one the ladder
+ * recommends — that pairing is what C-05 broke.
+ */
+declare const INSTALL_COMMAND = "npx clivly init";
+/**
+ * THE one producer of `next.command`. Six surfaces previously each invented
+ * their own "run this next" string, and one of them named a read-only command
+ * as the fix for a write problem (C-05). If you need a command for the
+ * next-action slot, call this — do not write another one.
+ */
+declare function nextAction(steps: IntegrationStep[], status: IntegrationStatus): NextAction | null;
+declare function computeIntegrationState(facts: IntegrationFacts): IntegrationState;
+//#endregion
+export { INSTALL_COMMAND, INTEGRATION_STEPS, INTEGRATION_STEP_LABELS, IntegrationFacts, IntegrationState, IntegrationStatus, IntegrationStep, NextAction, RunFact, STEP_PREREQUISITES, StepId, StepProblem, StepState, computeIntegrationState, deriveStatus, formatAge, nextAction, resolveSteps, stepIndex };

package/dist/integration-state.mjs

@@ -0,0 +1,232 @@
+//#region src/integration-state.ts
+const INTEGRATION_STEPS = [
+	"credential",
+	"application",
+	"schema",
+	"mapping",
+	"trigger",
+	"sync",
+	"widget"
+];
+const INTEGRATION_STEP_LABELS = {
+	credential: "Secure credential",
+	application: "Application connected",
+	schema: "Schema discovered",
+	mapping: "Entities mapped",
+	trigger: "Clivly can start a sync",
+	sync: "First sync observed",
+	widget: "Chat widget installed"
+};
+/** Each step's prerequisites. Ordering is enforced by a test, not convention. */
+const STEP_PREREQUISITES = {
+	credential: [],
+	application: ["credential"],
+	schema: ["application"],
+	mapping: ["schema"],
+	trigger: ["application"],
+	sync: ["mapping", "trigger"],
+	widget: ["application"]
+};
+function stepIndex(id) {
+	return INTEGRATION_STEPS.indexOf(id);
+}
+/** A heartbeat older than this means the app stopped checking in. */
+const HEARTBEAT_STALE_MS = 600 * 1e3;
+function formatAge(ms) {
+	if (ms < 6e4) return `${Math.max(1, Math.round(ms / 1e3))}s ago`;
+	if (ms < 36e5) return `${Math.round(ms / 6e4)}m ago`;
+	return `${Math.round(ms / 36e5)}h ago`;
+}
+function heartbeatAge(facts) {
+	return facts.lastHeartbeatAt === null ? null : facts.now - facts.lastHeartbeatAt;
+}
+/** Is the raw condition behind each step met, ignoring prerequisites? */
+function isSatisfied(id, facts) {
+	const age = heartbeatAge(facts);
+	switch (id) {
+		case "credential": return facts.hasCredential;
+		case "application": return age !== null && age < HEARTBEAT_STALE_MS;
+		case "schema": return facts.discoveredTableCount > 0;
+		case "mapping": return facts.mappedEntityCount > 0;
+		case "trigger": return facts.triggerConfigured;
+		case "sync": return facts.lastRun?.ok === true;
+		default: return facts.widgetInstalled;
+	}
+}
+function evidenceFor(id, facts) {
+	const age = heartbeatAge(facts);
+	if (id === "application" && age !== null) return `heartbeat ${formatAge(age)}`;
+	if (id === "schema" && facts.discoveredTableCount > 0) return `found ${facts.discoveredTableCount} tables`;
+	if (id === "mapping" && facts.mappedEntityCount > 0) return `${facts.mappedEntityCount} entity mapped`;
+	if (id === "trigger" && facts.triggerConfigured) return "trigger URL and secret set";
+	if (id === "sync" && facts.lastRun) return `last run ${formatAge(facts.now - facts.lastRun.at)}`;
+	return null;
+}
+function problemFor(id, facts) {
+	if (id === "sync" && facts.lastRun && !facts.lastRun.ok) return {
+		code: "sync_failed",
+		message: facts.lastRun.message ?? "The last sync run failed.",
+		fix: "Open the run log to see the host response."
+	};
+	if (id === "application") {
+		const age = heartbeatAge(facts);
+		if (age !== null && age >= HEARTBEAT_STALE_MS) return {
+			code: "heartbeat_stale",
+			message: `Your app stopped checking in ${formatAge(age)}.`,
+			fix: "Start your app, then run `npx clivly status`."
+		};
+		if (age === null && facts.everConnected) return {
+			code: "heartbeat_stale",
+			message: "Your application stopped checking in.",
+			fix: "Start your app, then run `npx clivly status`."
+		};
+	}
+	return null;
+}
+/**
+* Walk the ladder once. A step is `blocked` when an earlier step it needs has
+* not been satisfied — a prerequisite statement, not a verdict about this step
+* — and only the first unsatisfied step is `active`, so exactly one root cause
+* ever surfaces.
+*/
+function resolveSteps(facts) {
+	const satisfied = /* @__PURE__ */ new Set();
+	const steps = [];
+	let activeTaken = false;
+	for (const id of INTEGRATION_STEPS) {
+		const unmet = STEP_PREREQUISITES[id].find((need) => !satisfied.has(need));
+		const label = INTEGRATION_STEP_LABELS[id];
+		if (isSatisfied(id, facts)) {
+			satisfied.add(id);
+			steps.push({
+				id,
+				label,
+				state: "done",
+				blockedBy: null,
+				evidence: evidenceFor(id, facts),
+				problem: null
+			});
+			continue;
+		}
+		if (unmet !== void 0) {
+			steps.push({
+				id,
+				label,
+				state: "blocked",
+				blockedBy: unmet,
+				evidence: null,
+				problem: null
+			});
+			continue;
+		}
+		const problem = problemFor(id, facts);
+		let state = "active";
+		if (problem) state = "failed";
+		else if (id === "widget") state = "skipped";
+		const claimsAttention = state === "active" || state === "failed";
+		steps.push({
+			id,
+			label,
+			state: activeTaken && state === "active" ? "blocked" : state,
+			blockedBy: null,
+			evidence: evidenceFor(id, facts),
+			problem: activeTaken ? null : problem
+		});
+		if (claimsAttention) activeTaken = true;
+	}
+	return steps;
+}
+const STEP_STATUS_WHEN_ACTIVE = {
+	credential: "not_configured",
+	application: "awaiting_connection",
+	schema: "connected",
+	mapping: "mapping_required",
+	trigger: "trigger_required",
+	sync: "ready_to_sync",
+	widget: "healthy"
+};
+/**
+* Collapse the ladder to the single status the surfaces switch on. Live
+* conditions — a run in flight, a failure, a heartbeat gone quiet — win over
+* ladder position, because they describe the integration as it is now rather
+* than how far setup once got.
+*/
+function deriveStatus(steps, facts) {
+	if (facts.syncInFlight) return "syncing";
+	if (steps.find((step) => step.id === "application")?.problem?.code === "heartbeat_stale") return "disconnected";
+	if (steps.some((step) => step.state === "failed")) return "error";
+	const blocking = steps.find((step) => step.state === "active" || step.state === "blocked");
+	if (blocking) return STEP_STATUS_WHEN_ACTIVE[blocking.id];
+	return facts.warnings.length > 0 ? "warning" : "healthy";
+}
+/**
+* The command that installs Clivly into a host app. Exported because the connect
+* dialog prints it too, and it must be the same string as the one the ladder
+* recommends — that pairing is what C-05 broke.
+*/
+const INSTALL_COMMAND = "npx clivly init";
+const NEXT_BY_STEP = {
+	credential: {
+		label: "Create a credential",
+		command: null,
+		envFile: null
+	},
+	application: {
+		label: "Install Clivly in your app",
+		command: INSTALL_COMMAND,
+		envFile: ".env.local"
+	},
+	schema: {
+		label: "Check what the SDK reported",
+		command: "npx clivly status",
+		envFile: null
+	},
+	mapping: {
+		label: "Choose the table holding your people",
+		command: null,
+		envFile: null
+	},
+	trigger: {
+		label: "Let Clivly start a sync",
+		command: null,
+		envFile: null
+	},
+	sync: {
+		label: "Run the first sync",
+		command: "npx clivly sync",
+		envFile: null
+	},
+	widget: {
+		label: "Install the chat widget",
+		command: null,
+		envFile: null
+	}
+};
+/**
+* THE one producer of `next.command`. Six surfaces previously each invented
+* their own "run this next" string, and one of them named a read-only command
+* as the fix for a write problem (C-05). If you need a command for the
+* next-action slot, call this — do not write another one.
+*/
+function nextAction(steps, status) {
+	if (status === "healthy" || status === "syncing") return null;
+	const blocking = steps.find((step) => step.state === "failed") ?? steps.find((step) => step.state === "active");
+	if (!blocking) return null;
+	if (blocking.problem?.code === "heartbeat_stale") return {
+		label: "Reconnect your app",
+		command: "npx clivly status",
+		envFile: null
+	};
+	return NEXT_BY_STEP[blocking.id];
+}
+function computeIntegrationState(facts) {
+	const steps = resolveSteps(facts);
+	const status = deriveStatus(steps, facts);
+	return {
+		status,
+		steps,
+		next: nextAction(steps, status)
+	};
+}
+//#endregion
+export { INSTALL_COMMAND, INTEGRATION_STEPS, INTEGRATION_STEP_LABELS, STEP_PREREQUISITES, computeIntegrationState, deriveStatus, formatAge, nextAction, resolveSteps, stepIndex };

package/dist/mappings-config-B0W5bVZj.d.mts

@@ -0,0 +1,168 @@
+import { ClivlyEntitiesConfig } from "./entity-config.mjs";
+import { z } from "zod";
+//#region src/projection.d.ts
+/**
+ * Projection-backed custom mappings — one custom object derived from a base
+ * table plus explicit joins.
+ *
+ * A projection is deliberately narrow: equality joins only, direct column
+ * bindings only, no expressions and no aggregation. Everything a user can
+ * express here compiles to a single read-only view whose `id` column is
+ * provably unique per row, which is what lets the sync engine consume it
+ * unchanged.
+ *
+ * Refs address tables symbolically: `"base"` for the base table, or a join's
+ * `key`. Raw table names are never accepted in a ref, so a projection can
+ * never reach a table it did not declare.
+ */
+/** The reserved ref name for the projection's base table. */
+declare const BASE_REF = "base";
+declare const projectionRefSchema: z.ZodObject<{
+  table: z.ZodString;
+  column: z.ZodString;
+}, z.core.$strict>;
+type ProjectionRef = z.infer<typeof projectionRefSchema>;
+declare const projectionJoinSchema: z.ZodObject<{
+  key: z.ZodString;
+  table: z.ZodString;
+  type: z.ZodEnum<{
+    inner: "inner";
+    left: "left";
+  }>;
+  on: z.ZodArray<z.ZodObject<{
+    left: z.ZodObject<{
+      table: z.ZodString;
+      column: z.ZodString;
+    }, z.core.$strict>;
+    op: z.ZodLiteral<"eq">;
+    right: z.ZodObject<{
+      table: z.ZodString;
+      column: z.ZodString;
+    }, z.core.$strict>;
+  }, z.core.$strict>>;
+}, z.core.$strict>;
+type ProjectionJoin = z.infer<typeof projectionJoinSchema>;
+declare const projectionFieldBindingSchema: z.ZodObject<{
+  from: z.ZodObject<{
+    table: z.ZodString;
+    column: z.ZodString;
+  }, z.core.$strict>;
+}, z.core.$strict>;
+type ProjectionFieldBinding = z.infer<typeof projectionFieldBindingSchema>;
+declare const projectionIdentitySchema: z.ZodUnion<readonly [z.ZodObject<{
+  kind: z.ZodLiteral<"base_pk">;
+  column: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+  kind: z.ZodLiteral<"column">;
+  from: z.ZodObject<{
+    table: z.ZodString;
+    column: z.ZodString;
+  }, z.core.$strict>;
+}, z.core.$strict>, z.ZodObject<{
+  kind: z.ZodLiteral<"composite">;
+  parts: z.ZodArray<z.ZodObject<{
+    table: z.ZodString;
+    column: z.ZodString;
+  }, z.core.$strict>>;
+}, z.core.$strict>]>;
+type ProjectionIdentity = z.infer<typeof projectionIdentitySchema>;
+declare const projectionSchema: z.ZodObject<{
+  version: z.ZodLiteral<1>;
+  kind: z.ZodLiteral<"projection">;
+  entityKey: z.ZodString;
+  baseTable: z.ZodString;
+  joins: z.ZodArray<z.ZodObject<{
+    key: z.ZodString;
+    table: z.ZodString;
+    type: z.ZodEnum<{
+      inner: "inner";
+      left: "left";
+    }>;
+    on: z.ZodArray<z.ZodObject<{
+      left: z.ZodObject<{
+        table: z.ZodString;
+        column: z.ZodString;
+      }, z.core.$strict>;
+      op: z.ZodLiteral<"eq">;
+      right: z.ZodObject<{
+        table: z.ZodString;
+        column: z.ZodString;
+      }, z.core.$strict>;
+    }, z.core.$strict>>;
+  }, z.core.$strict>>;
+  fieldBindings: z.ZodRecord<z.ZodString, z.ZodObject<{
+    from: z.ZodObject<{
+      table: z.ZodString;
+      column: z.ZodString;
+    }, z.core.$strict>;
+  }, z.core.$strict>>;
+  identity: z.ZodUnion<readonly [z.ZodObject<{
+    kind: z.ZodLiteral<"base_pk">;
+    column: z.ZodOptional<z.ZodString>;
+  }, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"column">;
+    from: z.ZodObject<{
+      table: z.ZodString;
+      column: z.ZodString;
+    }, z.core.$strict>;
+  }, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"composite">;
+    parts: z.ZodArray<z.ZodObject<{
+      table: z.ZodString;
+      column: z.ZodString;
+    }, z.core.$strict>>;
+  }, z.core.$strict>]>;
+}, z.core.$strict>;
+type ProjectionMapping = z.infer<typeof projectionSchema>;
+/**
+ * Every column ref an identity depends on. `basePkColumn` is the base table's
+ * discovered PK, used only when a `base_pk` identity omits an explicit column.
+ */
+declare function identityRefs(identity: ProjectionIdentity, basePkColumn: string): ProjectionRef[];
+//#endregion
+//#region 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;
+  /**
+   * Advanced mapping: a base table plus explicit joins. When set, this — not
+   * `fieldMap` — is the authored source of truth, and `sourceTable` merely
+   * mirrors `projection.baseTable`.
+   */
+  projection?: ProjectionMapping | 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 { ProjectionIdentity as a, ProjectionRef as c, ProjectionFieldBinding as i, identityRefs as l, mappingsToEntitiesConfig as n, ProjectionJoin as o, BASE_REF as r, ProjectionMapping as s, EntityMappingRow as t, projectionSchema as u };