clivly 0.2.0 → 0.2.1

package/sdk.cjs

@@ -0,0 +1,7 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_sdk = require("./sdk-CP_mYZa5.cjs");
+exports.ClivlyAuthError = require_sdk.ClivlyAuthError;
+exports.ClivlyError = require_sdk.ClivlyError;
+exports.ClivlyNetworkError = require_sdk.ClivlyNetworkError;
+exports.ClivlyRateLimitError = require_sdk.ClivlyRateLimitError;
+exports.createClivlySDK = require_sdk.createClivlySDK;

package/sdk.d.cts

@@ -0,0 +1,33 @@
+import { a as ClivlySDKConfig, c as DiscoveredTable, i as ClivlySDK, l as DoctorCheck, n as ClivlyConnectReason, o as ClivlyUser, r as ClivlyConnectResult, s as CursorStore, u as DoctorReport } from "./namespace-probe-BtS0nXcr.cjs";
+
+//#region ../sdk/src/errors.d.ts
+declare class ClivlyError extends Error {
+  /** HTTP status, or null when the request never completed (network error). */
+  readonly status: number | null;
+  readonly reason: ClivlyConnectResult["reason"];
+  /** Whether a retry could plausibly succeed (network, 429, 5xx). */
+  readonly retryable: boolean;
+  constructor(result: ClivlyConnectResult, message?: string);
+  /**
+   * Build the error subclass matching a failed result's reason, or `null` when
+   * the result is `ok`.
+   */
+  static from(result: ClivlyConnectResult): ClivlyError | null;
+}
+/** The API key was rejected (401) or lacks access (403). Not retryable. */
+declare class ClivlyAuthError extends ClivlyError {}
+/** Rate limited (429). Retryable after backoff / `Retry-After`. */
+declare class ClivlyRateLimitError extends ClivlyError {}
+/** The request never reached the server (network/DNS/TLS). Retryable. */
+declare class ClivlyNetworkError extends ClivlyError {}
+//#endregion
+//#region ../sdk/src/index.d.ts
+/**
+ * Create the Clivly SDK. The implemented surface — heartbeat/discovery reporting
+ * and the auth-verify handler — connects a developer's app to a running Clivly
+ * backend today. Tunnel management and CRM write-back are scaffolded (see the
+ * clearly-marked TODOs) and land with the Cloudflare infrastructure.
+ */
+declare function createClivlySDK(config: ClivlySDKConfig): ClivlySDK;
+//#endregion
+export { ClivlyAuthError, type ClivlyConnectReason, type ClivlyConnectResult, ClivlyError, ClivlyNetworkError, ClivlyRateLimitError, type ClivlySDK, type ClivlySDKConfig, type ClivlyUser, type CursorStore, type DiscoveredTable, type DoctorCheck, type DoctorReport, createClivlySDK };

package/sdk.d.mts

@@ -0,0 +1,33 @@
+import { a as ClivlySDKConfig, c as DiscoveredTable, i as ClivlySDK, l as DoctorCheck, n as ClivlyConnectReason, o as ClivlyUser, r as ClivlyConnectResult, s as CursorStore, u as DoctorReport } from "./namespace-probe-CYMie-BI.mjs";
+
+//#region ../sdk/src/errors.d.ts
+declare class ClivlyError extends Error {
+  /** HTTP status, or null when the request never completed (network error). */
+  readonly status: number | null;
+  readonly reason: ClivlyConnectResult["reason"];
+  /** Whether a retry could plausibly succeed (network, 429, 5xx). */
+  readonly retryable: boolean;
+  constructor(result: ClivlyConnectResult, message?: string);
+  /**
+   * Build the error subclass matching a failed result's reason, or `null` when
+   * the result is `ok`.
+   */
+  static from(result: ClivlyConnectResult): ClivlyError | null;
+}
+/** The API key was rejected (401) or lacks access (403). Not retryable. */
+declare class ClivlyAuthError extends ClivlyError {}
+/** Rate limited (429). Retryable after backoff / `Retry-After`. */
+declare class ClivlyRateLimitError extends ClivlyError {}
+/** The request never reached the server (network/DNS/TLS). Retryable. */
+declare class ClivlyNetworkError extends ClivlyError {}
+//#endregion
+//#region ../sdk/src/index.d.ts
+/**
+ * Create the Clivly SDK. The implemented surface — heartbeat/discovery reporting
+ * and the auth-verify handler — connects a developer's app to a running Clivly
+ * backend today. Tunnel management and CRM write-back are scaffolded (see the
+ * clearly-marked TODOs) and land with the Cloudflare infrastructure.
+ */
+declare function createClivlySDK(config: ClivlySDKConfig): ClivlySDK;
+//#endregion
+export { ClivlyAuthError, type ClivlyConnectReason, type ClivlyConnectResult, ClivlyError, ClivlyNetworkError, ClivlyRateLimitError, type ClivlySDK, type ClivlySDKConfig, type ClivlyUser, type CursorStore, type DiscoveredTable, type DoctorCheck, type DoctorReport, createClivlySDK };

package/sdk.mjs

@@ -0,0 +1,2 @@
+import { a as ClivlyRateLimitError, i as ClivlyNetworkError, n as ClivlyAuthError, r as ClivlyError, t as createClivlySDK } from "./sdk-BZUn6wzs.mjs";
+export { ClivlyAuthError, ClivlyError, ClivlyNetworkError, ClivlyRateLimitError, createClivlySDK };

package/sync-engine-DUc0qWgo.cjs

@@ -0,0 +1,230 @@
+const require_view_compiler = require("./view-compiler-BHzbI9b7.cjs");
+//#region ../core/src/sync-engine.ts
+/**
+* Diff a view's rows against the current mirror population for one entity.
+*
+* - source row with no mirror row      → create
+* - source row with a live mirror row  → update (overwrite identity fields)
+* - source row with an archived mirror → restore (re-activate + update)
+* - live mirror row absent from source → archive (soft delete, keep history)
+* - archived mirror row absent from source → no-op
+*
+* Source rows are de-duplicated by the reconciliation key (first wins). In
+* simple mode (default) the key is `sourceRef`. In composite mode — used for
+* `through` (join-table) entities, where the compiled view fans a person out
+* into one row per membership — the key is `(sourceRef, companyRef)`, so a
+* person in several companies materializes one mirror row per company and a
+* single membership leaving archives only that one row.
+*/
+function reconcile(source, mirror, opts = {}) {
+	const keyOf = (sourceRef, companyRef) => opts.composite ? `${sourceRef}\0${companyRef ?? ""}` : sourceRef;
+	const seen = /* @__PURE__ */ new Set();
+	const rows = [];
+	for (const row of source) {
+		const key = keyOf(row.sourceRef, row.companyRef ?? null);
+		if (!seen.has(key)) {
+			seen.add(key);
+			rows.push(row);
+		}
+	}
+	const byKey = new Map(mirror.map((m) => [keyOf(m.sourceRef, m.companyRef), m]));
+	const liveKeys = /* @__PURE__ */ new Set();
+	const actions = [];
+	for (const row of rows) {
+		const companyRef = row.companyRef ?? null;
+		const key = keyOf(row.sourceRef, companyRef);
+		liveKeys.add(key);
+		const existing = byKey.get(key);
+		if (!existing) actions.push({
+			kind: "create",
+			sourceRef: row.sourceRef,
+			fields: row.fields,
+			companyRef
+		});
+		else if (existing.archivedAt) actions.push({
+			kind: "restore",
+			id: existing.id,
+			sourceRef: row.sourceRef,
+			fields: row.fields,
+			companyRef
+		});
+		else actions.push({
+			kind: "update",
+			id: existing.id,
+			sourceRef: row.sourceRef,
+			fields: row.fields,
+			companyRef
+		});
+	}
+	for (const m of mirror) {
+		const key = keyOf(m.sourceRef, m.companyRef);
+		if (!(liveKeys.has(key) || m.archivedAt)) actions.push({
+			kind: "archive",
+			id: m.id,
+			sourceRef: m.sourceRef
+		});
+	}
+	return actions;
+}
+const CONCEPT_ORDER = {
+	company: 0,
+	contact: 1
+};
+/** Companies before contacts, so contact company_refs resolve to a live mirror. */
+function syncOrder(a, b) {
+	return (CONCEPT_ORDER[a.concept] ?? 99) - (CONCEPT_ORDER[b.concept] ?? 99);
+}
+async function resolveActions(store, actions) {
+	const refs = /* @__PURE__ */ new Set();
+	for (const action of actions) if (action.kind !== "archive" && action.companyRef) refs.add(action.companyRef);
+	const resolved = refs.size ? await store.resolveCompanyRefs([...refs]) : /* @__PURE__ */ new Map();
+	return actions.map((action) => {
+		if (action.kind === "archive") return action;
+		const companyId = action.companyRef ? resolved.get(action.companyRef) ?? null : null;
+		return {
+			kind: action.kind,
+			id: "id" in action ? action.id : "",
+			sourceRef: action.sourceRef,
+			fields: action.fields,
+			companyId,
+			companySourceRef: action.companyRef ?? null
+		};
+	});
+}
+function emptyTally() {
+	return {
+		create: 0,
+		update: 0,
+		restore: 0,
+		archive: 0
+	};
+}
+/**
+* An entity whose company relationship is a `through` (join-table) join fans out
+* into one source row per membership, so its mirror must be keyed compositely.
+*/
+function isCompositeEntity(config, entityKey) {
+	const entity = config.entities[entityKey];
+	if (!entity?.relationships) return false;
+	return Object.values(entity.relationships).some((rel) => "through" in rel.via);
+}
+/**
+* Run a full sync: compile the config's views, then reconcile + persist each,
+* companies first. Returns per-entity and total action counts.
+*/
+async function runSync(config, store, options = {}) {
+	const allViews = require_view_compiler.compileEntityViews(config, options).sort(syncOrder);
+	const views = options.sample ? allViews.filter((v) => v.entityKey === options.sample?.entityKey) : allViews;
+	const entities = [];
+	const totals = {
+		created: 0,
+		updated: 0,
+		restored: 0,
+		archived: 0
+	};
+	for (const view of views) {
+		const objectTypeId = config.entities[view.entityKey]?.targetObjectTypeId;
+		const [source, mirror] = await Promise.all([store.readView(view, options.sample ? { limit: 1 } : void 0), store.listMirror({
+			concept: view.concept,
+			role: view.role,
+			objectTypeId
+		})]);
+		const actions = reconcile(source, mirror, { composite: isCompositeEntity(config, view.entityKey) }).filter((a) => !(options.sample && a.kind === "archive"));
+		const persistActions = await resolveActions(store, actions);
+		await store.persist({
+			concept: view.concept,
+			role: view.role,
+			objectTypeId,
+			actions: persistActions
+		});
+		const counts = emptyTally();
+		for (const action of actions) counts[action.kind] += 1;
+		const result = {
+			entityKey: view.entityKey,
+			concept: view.concept,
+			role: view.role,
+			created: counts.create,
+			updated: counts.update,
+			restored: counts.restore,
+			archived: counts.archive
+		};
+		entities.push(result);
+		totals.created += result.created;
+		totals.updated += result.updated;
+		totals.restored += result.restored;
+		totals.archived += result.archived;
+	}
+	return {
+		entities,
+		totals
+	};
+}
+function isEmptyValue(value) {
+	return value === null || value === void 0 || value === "";
+}
+/**
+* Sample-scoped data-quality warnings over projected preview rows. Each mapped
+* (or required-but-unmapped) field yields at most one warning, by precedence:
+* a required field empty in ≥1 row → `K/N` form; an optional field empty in
+* ALL rows → all-empty form; zero source rows → a single table-level warning.
+*/
+function computeSampleWarnings(rows, requiredFields, sourceTable) {
+	if (rows.length === 0) return [{ message: `no rows found in ${sourceTable}` }];
+	const required = new Set(requiredFields);
+	const fields = new Set(requiredFields);
+	for (const row of rows) for (const key of Object.keys(row.fields)) fields.add(key);
+	const warnings = [];
+	for (const field of [...fields].sort()) {
+		const emptyCount = rows.filter((row) => isEmptyValue(row.fields[field])).length;
+		if (required.has(field)) {
+			if (emptyCount > 0) warnings.push({
+				field,
+				message: `${field} empty in ${emptyCount}/${rows.length} sampled`
+			});
+		} else if (emptyCount === rows.length) warnings.push({
+			field,
+			message: `${field} is empty in all ${rows.length} sampled rows`
+		});
+	}
+	return warnings;
+}
+/**
+* Zero-write preview: read ≤`limit` rows through the compiled view (a pure
+* SELECT whose SQL already projects each row into its mapped fields) and
+* compute sample warnings. Calls ONLY `store.readView` — never a write path —
+* so it can never mutate the mirror. The distinct, write-one-row sibling is
+* `runSync`'s sample mode (T13).
+*/
+async function previewSync(store, view, opts) {
+	const rows = await store.readView(view, { limit: opts.limit });
+	return {
+		rows,
+		sampledCount: rows.length,
+		warnings: computeSampleWarnings(rows, opts.requiredFields, opts.sourceTable)
+	};
+}
+//#endregion
+Object.defineProperty(exports, "computeSampleWarnings", {
+	enumerable: true,
+	get: function() {
+		return computeSampleWarnings;
+	}
+});
+Object.defineProperty(exports, "previewSync", {
+	enumerable: true,
+	get: function() {
+		return previewSync;
+	}
+});
+Object.defineProperty(exports, "reconcile", {
+	enumerable: true,
+	get: function() {
+		return reconcile;
+	}
+});
+Object.defineProperty(exports, "runSync", {
+	enumerable: true,
+	get: function() {
+		return runSync;
+	}
+});

package/sync-engine-DWnQPjV3.d.mts

@@ -0,0 +1,183 @@
+import { a as ClivlyEntitiesConfig } from "./entity-config-D1DFyeUp.mjs";
+import { n as CompiledView, t as CompileOptions } from "./view-compiler-i_xFf-L0.mjs";
+
+//#region ../core/src/sync-engine.d.ts
+/**
+ * Sync engine (Phase 3) — materializes the read-only entity views into Clivly's
+ * own mirror tables (`crm_companies`, `crm_contacts`).
+ *
+ * The reconciliation is the heart of the design: rows present in a view are
+ * created or updated in the mirror; rows that *leave* a view (e.g. an owner
+ * demoted to a member) are **archived, not deleted**, so their deals/activities
+ * survive. Identity fields are host-owned and overwritten each run; Clivly-owned
+ * CRM fields are never touched here.
+ *
+ * `reconcile()` is a pure function and independently testable. `runSync()`
+ * orchestrates: compile views → for each (companies first, so contact
+ * `company_ref`s resolve to a live `crm_companies.id`) read the view, reconcile
+ * against the current mirror, resolve company refs, and persist. All DB I/O is
+ * behind the `SyncStore` port — core stays ORM-agnostic; the SDK/drizzle
+ * package provides the concrete store.
+ */
+/** A row read from a compiled view (what Postgres returns). */
+interface SourceRow {
+  /** Host-side company key from `<relationship>_ref`; resolved before persist. */
+  companyRef?: string | null;
+  /** Mapped identity fields (clivly field → value). */
+  fields: Record<string, string | null>;
+  /** The source primary key — becomes the mirror row's `source_ref`. */
+  sourceRef: string;
+}
+/** An existing mirror row, as far as reconciliation needs to know. */
+interface MirrorRecord {
+  archivedAt: Date | null;
+  /** Host-side company key; only consulted in composite (join-table) mode. */
+  companyRef: string | null;
+  id: string;
+  sourceRef: string;
+}
+type SyncAction = {
+  kind: "create";
+  sourceRef: string;
+  fields: Record<string, string | null>;
+  companyRef: string | null;
+} | {
+  kind: "update";
+  id: string;
+  sourceRef: string;
+  fields: Record<string, string | null>;
+  companyRef: string | null;
+} | {
+  kind: "restore";
+  id: string;
+  sourceRef: string;
+  fields: Record<string, string | null>;
+  companyRef: string | null;
+} | {
+  kind: "archive";
+  id: string;
+  sourceRef: string;
+};
+/** A persist action with the company ref resolved to a `crm_companies.id`. */
+type PersistAction = {
+  kind: "create";
+  sourceRef: string;
+  fields: Record<string, string | null>;
+  companyId: string | null;
+  companySourceRef: string | null;
+} | {
+  kind: "update";
+  id: string;
+  sourceRef: string;
+  fields: Record<string, string | null>;
+  companyId: string | null;
+  companySourceRef: string | null;
+} | {
+  kind: "restore";
+  id: string;
+  sourceRef: string;
+  fields: Record<string, string | null>;
+  companyId: string | null;
+  companySourceRef: string | null;
+} | {
+  kind: "archive";
+  id: string;
+  sourceRef: string;
+};
+/**
+ * Diff a view's rows against the current mirror population for one entity.
+ *
+ * - source row with no mirror row      → create
+ * - source row with a live mirror row  → update (overwrite identity fields)
+ * - source row with an archived mirror → restore (re-activate + update)
+ * - live mirror row absent from source → archive (soft delete, keep history)
+ * - archived mirror row absent from source → no-op
+ *
+ * Source rows are de-duplicated by the reconciliation key (first wins). In
+ * simple mode (default) the key is `sourceRef`. In composite mode — used for
+ * `through` (join-table) entities, where the compiled view fans a person out
+ * into one row per membership — the key is `(sourceRef, companyRef)`, so a
+ * person in several companies materializes one mirror row per company and a
+ * single membership leaving archives only that one row.
+ */
+declare function reconcile(source: SourceRow[], mirror: MirrorRecord[], opts?: {
+  composite?: boolean;
+}): SyncAction[];
+/** DB I/O port. The concrete store lives in the SDK/drizzle package. */
+interface SyncStore {
+  /** Current mirror rows for a concept + role (including archived). */
+  listMirror(input: {
+    concept: string;
+    role: string; /** Target custom-object type id, for `concept: "custom"` entities. */
+    objectTypeId?: string;
+  }): Promise<MirrorRecord[]>;
+  /** Apply the resolved actions to the mirror table for this concept + role. */
+  persist(input: {
+    concept: string;
+    role: string; /** Target custom-object type id, for `concept: "custom"` entities. */
+    objectTypeId?: string;
+    actions: PersistAction[];
+  }): Promise<void>;
+  /**
+   * Execute the view's SQL and return its rows. `opts.limit`, when given,
+   * caps the number of rows returned (used by `runSync`'s sample mode).
+   */
+  readView(view: CompiledView, opts?: {
+    limit?: number;
+  }): Promise<SourceRow[]>;
+  /** Map host-side company refs → `crm_companies.id` (already-synced companies only). */
+  resolveCompanyRefs(refs: string[]): Promise<Map<string, string>>;
+}
+interface EntitySyncResult {
+  archived: number;
+  concept: string;
+  created: number;
+  entityKey: string;
+  restored: number;
+  role: string;
+  updated: number;
+}
+interface SyncResult {
+  entities: EntitySyncResult[];
+  totals: {
+    created: number;
+    updated: number;
+    restored: number;
+    archived: number;
+  };
+}
+/**
+ * Run a full sync: compile the config's views, then reconcile + persist each,
+ * companies first. Returns per-entity and total action counts.
+ */
+declare function runSync(config: ClivlyEntitiesConfig, store: SyncStore, options?: CompileOptions): Promise<SyncResult>;
+interface PreviewWarning {
+  field?: string;
+  message: string;
+}
+interface PreviewResult {
+  rows: SourceRow[];
+  sampledCount: number;
+  warnings: PreviewWarning[];
+}
+/**
+ * Sample-scoped data-quality warnings over projected preview rows. Each mapped
+ * (or required-but-unmapped) field yields at most one warning, by precedence:
+ * a required field empty in ≥1 row → `K/N` form; an optional field empty in
+ * ALL rows → all-empty form; zero source rows → a single table-level warning.
+ */
+declare function computeSampleWarnings(rows: SourceRow[], requiredFields: string[], sourceTable: string): PreviewWarning[];
+/**
+ * Zero-write preview: read ≤`limit` rows through the compiled view (a pure
+ * SELECT whose SQL already projects each row into its mapped fields) and
+ * compute sample warnings. Calls ONLY `store.readView` — never a write path —
+ * so it can never mutate the mirror. The distinct, write-one-row sibling is
+ * `runSync`'s sample mode (T13).
+ */
+declare function previewSync(store: SyncStore, view: CompiledView, opts: {
+  limit: number;
+  requiredFields: string[];
+  sourceTable: string;
+}): Promise<PreviewResult>;
+//#endregion
+export { PreviewWarning as a, SyncResult as c, previewSync as d, reconcile as f, PreviewResult as i, SyncStore as l, MirrorRecord as n, SourceRow as o, runSync as p, PersistAction as r, SyncAction as s, EntitySyncResult as t, computeSampleWarnings as u };