@clivly/core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Clivly
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,29 @@
+# @clivly/core
+
+ORM- and auth-agnostic contracts and shared domain types for [Clivly](https://clivly.com) — the CRM that lives inside your app.
+
+This package defines the interfaces that ORM and auth adapters implement. It has no runtime dependencies.
+
+## Exports
+
+| Entry | Contents |
+|---|---|
+| `.` | Everything below, re-exported |
+| `@clivly/core/adapter` | `CRMAdapter` — the interface every ORM implementation fulfils (org-scoped; contacts, companies, deals, tasks, activities) |
+| `@clivly/core/auth-adapter` | `ClivlyAuthAdapter`, `authCustom()`, `MembershipResolver` — pluggable host-app identity + the `crm_members` authorization layer |
+| `@clivly/core/types` | Shared domain types (`Contact`, `Company`, `Deal`, `Task`, `Note`, `Activity`, inputs, filters, `CrmRole`) |
+
+## Usage
+
+```ts
+import type { CRMAdapter } from "@clivly/core";
+
+// packages/drizzle implements this; Prisma/Kysely can follow.
+function useAdapter(crm: CRMAdapter) {
+  return crm.getContacts(orgId);
+}
+```
+
+## License
+
+MIT

package/dist/adapter.d.mts

@@ -0,0 +1,33 @@
+import { Activity, Company, Contact, ContactFilters, CreateActivityInput, CreateCompanyInput, CreateContactInput, CreateDealInput, CreateTaskInput, Deal, Task, TaskFilters, UpdateContactInput, UpdateTaskInput } from "./types.mjs";
+
+//#region src/adapter.d.ts
+/**
+ * The contract every ORM implementation fulfils. `packages/drizzle` is the first
+ * implementation; Prisma/Kysely/TypeORM can follow without changes to consumers.
+ *
+ * Every method is scoped to a single organization (`orgId`) — the adapter is the
+ * one place tenant isolation is enforced for CRM data. Implementations only ever
+ * read/write Clivly-owned `crm_*` tables; they never mutate host business tables.
+ */
+interface CRMAdapter {
+  archiveTask(orgId: string, id: string): Promise<Task>;
+  completeTask(orgId: string, id: string): Promise<Task>;
+  createActivity(orgId: string, data: CreateActivityInput): Promise<Activity>;
+  createCompany(orgId: string, data: CreateCompanyInput): Promise<Company>;
+  createContact(orgId: string, data: CreateContactInput): Promise<Contact>;
+  createDeal(orgId: string, data: CreateDealInput): Promise<Deal>;
+  createTask(orgId: string, data: CreateTaskInput): Promise<Task>;
+  getActivities(orgId: string, contactId: string): Promise<Activity[]>;
+  getCompanies(orgId: string): Promise<Company[]>;
+  getContact(orgId: string, id: string): Promise<Contact | null>;
+  getContacts(orgId: string, filters?: ContactFilters): Promise<Contact[]>;
+  getDeals(orgId: string): Promise<Deal[]>;
+  getTasks(orgId: string, filters?: TaskFilters): Promise<Task[]>;
+  reopenTask(orgId: string, id: string): Promise<Task>;
+  updateContact(orgId: string, id: string, data: UpdateContactInput): Promise<Contact>;
+  updateDealStage(orgId: string, id: string, stage: Deal["stage"]): Promise<Deal>;
+  updateTask(orgId: string, id: string, data: UpdateTaskInput): Promise<Task>;
+  updateTaskStatus(orgId: string, id: string, status: Task["status"]): Promise<Task>;
+}
+//#endregion
+export { CRMAdapter };

package/dist/adapter.mjs

@@ -0,0 +1 @@
+export {};

package/dist/auth-adapter.d.mts

@@ -0,0 +1,30 @@
+import { CrmRole } from "./types.mjs";
+
+//#region src/auth-adapter.d.ts
+interface ClivlyUser {
+  email: string;
+  id: string;
+  name?: string;
+}
+/**
+ * Bridges any host auth system into Clivly. Ship adapters wrap a concrete SDK
+ * (`@clivly/auth-clerk`, `@clivly/auth-workos`), and `authCustom` wraps an
+ * arbitrary `(req) => user` resolver.
+ *
+ * This answers "who is this person?" only. Authorization ("what can they do in
+ * this org?") is the separate `crm_members` layer — see `MembershipResolver`.
+ */
+interface ClivlyAuthAdapter {
+  getUser(req: Request): Promise<ClivlyUser | null>;
+}
+declare function authCustom(resolver: (req: Request) => Promise<ClivlyUser | null> | ClivlyUser | null): ClivlyAuthAdapter;
+interface CrmMembership {
+  orgId: string;
+  role: CrmRole;
+  userId: string;
+}
+interface MembershipResolver {
+  getMembership(userId: string, orgId: string): Promise<CrmMembership | null>;
+}
+//#endregion
+export { ClivlyAuthAdapter, ClivlyUser, CrmMembership, MembershipResolver, authCustom };

package/dist/auth-adapter.mjs

@@ -0,0 +1,6 @@
+//#region src/auth-adapter.ts
+function authCustom(resolver) {
+	return { getUser: async (req) => await resolver(req) };
+}
+//#endregion
+export { authCustom };

package/dist/entity-config.d.mts

@@ -0,0 +1,258 @@
+import { z } from "zod";
+
+//#region src/entity-config.d.ts
+/**
+ * Entity Config v2 — the declarative contract that turns Clivly's "schema-aware"
+ * promise into a real capability.
+ *
+ * A CRM entity is no longer a flat table name. It is a *derived entity*: a
+ * filtered slice of a host table (`source` + `filter`), a column allowlist
+ * (`fields` + `readOnly`), and declared `relationships` to other entities. The
+ * same host table can back several entities (e.g. `users` → owners + members)
+ * distinguished by `role`.
+ *
+ * This module is the Phase 1 slice: types, schema, `defineClivlyConfig` (a
+ * structural helper) and `validateEntitiesConfig` (semantic validation against
+ * the host's discovered schema). It performs NO DB access and generates no SQL —
+ * the view compiler (Phase 2) and sync engine (Phase 3) consume this contract.
+ */
+/** Canonical CRM concepts a host entity can map onto. */
+declare const CRM_CONCEPTS: readonly ["contact", "company", "deal", "activity", "conversation", "note"];
+type CrmConcept = (typeof CRM_CONCEPTS)[number];
+/**
+ * The canonical `fields` keys the mirror actually persists, per concept — the
+ * crm_* columns the sync store writes. An entity's `fields` map keys must be one
+ * of these: a non-canonical key (e.g. `fullName` instead of `name`) validates
+ * structurally but has no destination column, so the store silently writes an
+ * empty value. `validateEntitiesConfig` flags those.
+ *
+ * This is the single source of truth — the Drizzle store imports it, so the
+ * two can't drift (the drift is what made the silent-data-loss trap possible).
+ * Concepts absent here aren't materialized yet, so their field keys are
+ * unconstrained.
+ */
+declare const CANONICAL_FIELDS: {
+  readonly contact: readonly ["name", "email", "title", "status"];
+  readonly company: readonly ["name", "domain", "industry", "size"];
+};
+declare const filterValueSchema: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodUnion<readonly [z.ZodObject<{
+  eq: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>;
+}, z.core.$strict>, z.ZodObject<{
+  ne: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>;
+}, z.core.$strict>, z.ZodObject<{
+  in: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+}, z.core.$strict>, z.ZodObject<{
+  notIn: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+}, z.core.$strict>, z.ZodObject<{
+  isNull: z.ZodLiteral<true>;
+}, z.core.$strict>, z.ZodObject<{
+  isNotNull: z.ZodLiteral<true>;
+}, z.core.$strict>]>]>;
+/** `$raw` is a reserved key; a column literally named `$raw` is not addressable. */
+declare const filterSchema: z.ZodUnion<readonly [z.ZodObject<{
+  $raw: z.ZodString;
+}, z.core.$strict>, z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodUnion<readonly [z.ZodObject<{
+  eq: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>;
+}, z.core.$strict>, z.ZodObject<{
+  ne: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>;
+}, z.core.$strict>, z.ZodObject<{
+  in: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+}, z.core.$strict>, z.ZodObject<{
+  notIn: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+}, z.core.$strict>, z.ZodObject<{
+  isNull: z.ZodLiteral<true>;
+}, z.core.$strict>, z.ZodObject<{
+  isNotNull: z.ZodLiteral<true>;
+}, z.core.$strict>]>]>>]>;
+type FilterExpr = z.infer<typeof filterSchema>;
+/** A single column predicate value (scalar shorthand or operator object). */
+type FilterValue = z.infer<typeof filterValueSchema>;
+/**
+ * How the link between two entities is expressed in the host schema:
+ * - `fkOn: "company"` — FK lives on the company table (e.g. organizations.owner_id)
+ * - `fkOn: "contact"` — FK lives on the contact table (e.g. users.organization_id)
+ * - `through`         — a join table sits between them (many-to-many, role often here)
+ * - `$raw`            — opaque SQL join fragment (escape hatch; not schema-validated)
+ *
+ * `column` and the join-table keys are `table.column` or bare `column` strings.
+ */
+declare const relationshipViaSchema: z.ZodUnion<readonly [z.ZodObject<{
+  fkOn: z.ZodEnum<{
+    contact: "contact";
+    company: "company";
+  }>;
+  column: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+  through: z.ZodString;
+  localKey: z.ZodString;
+  foreignKey: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+  $raw: z.ZodString;
+}, z.core.$strict>]>;
+type RelationshipVia = z.infer<typeof relationshipViaSchema>;
+declare const relationshipSchema: z.ZodObject<{
+  entity: z.ZodString;
+  via: z.ZodUnion<readonly [z.ZodObject<{
+    fkOn: z.ZodEnum<{
+      contact: "contact";
+      company: "company";
+    }>;
+    column: z.ZodString;
+  }, z.core.$strict>, z.ZodObject<{
+    through: z.ZodString;
+    localKey: z.ZodString;
+    foreignKey: z.ZodString;
+  }, z.core.$strict>, z.ZodObject<{
+    $raw: z.ZodString;
+  }, z.core.$strict>]>;
+}, z.core.$strict>;
+type RelationshipSpec = z.infer<typeof relationshipSchema>;
+/** A named map of relationships, as stored on an entity / in the mappings row. */
+declare const relationshipsSchema: z.ZodRecord<z.ZodString, z.ZodObject<{
+  entity: z.ZodString;
+  via: z.ZodUnion<readonly [z.ZodObject<{
+    fkOn: z.ZodEnum<{
+      contact: "contact";
+      company: "company";
+    }>;
+    column: z.ZodString;
+  }, z.core.$strict>, z.ZodObject<{
+    through: z.ZodString;
+    localKey: z.ZodString;
+    foreignKey: z.ZodString;
+  }, z.core.$strict>, z.ZodObject<{
+    $raw: z.ZodString;
+  }, z.core.$strict>]>;
+}, z.core.$strict>>;
+type RelationshipsMap = z.infer<typeof relationshipsSchema>;
+declare const entitySchema: z.ZodObject<{
+  concept: z.ZodEnum<{
+    contact: "contact";
+    company: "company";
+    deal: "deal";
+    activity: "activity";
+    conversation: "conversation";
+    note: "note";
+  }>;
+  source: z.ZodString;
+  role: z.ZodOptional<z.ZodString>;
+  filter: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
+    $raw: z.ZodString;
+  }, z.core.$strict>, z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodUnion<readonly [z.ZodObject<{
+    eq: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>;
+  }, z.core.$strict>, z.ZodObject<{
+    ne: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>;
+  }, z.core.$strict>, z.ZodObject<{
+    in: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+  }, z.core.$strict>, z.ZodObject<{
+    notIn: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+  }, z.core.$strict>, z.ZodObject<{
+    isNull: z.ZodLiteral<true>;
+  }, z.core.$strict>, z.ZodObject<{
+    isNotNull: z.ZodLiteral<true>;
+  }, z.core.$strict>]>]>>]>>;
+  fields: z.ZodRecord<z.ZodString, z.ZodString>;
+  readOnly: z.ZodOptional<z.ZodArray<z.ZodString>>;
+  relationships: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+    entity: z.ZodString;
+    via: z.ZodUnion<readonly [z.ZodObject<{
+      fkOn: z.ZodEnum<{
+        contact: "contact";
+        company: "company";
+      }>;
+      column: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+      through: z.ZodString;
+      localKey: z.ZodString;
+      foreignKey: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+      $raw: z.ZodString;
+    }, z.core.$strict>]>;
+  }, z.core.$strict>>>;
+}, z.core.$strict>;
+type ClivlyEntityConfig = z.infer<typeof entitySchema>;
+declare const entitiesConfigSchema: z.ZodObject<{
+  entities: z.ZodRecord<z.ZodString, z.ZodObject<{
+    concept: z.ZodEnum<{
+      contact: "contact";
+      company: "company";
+      deal: "deal";
+      activity: "activity";
+      conversation: "conversation";
+      note: "note";
+    }>;
+    source: z.ZodString;
+    role: z.ZodOptional<z.ZodString>;
+    filter: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
+      $raw: z.ZodString;
+    }, z.core.$strict>, z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodUnion<readonly [z.ZodObject<{
+      eq: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>;
+    }, z.core.$strict>, z.ZodObject<{
+      ne: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>;
+    }, z.core.$strict>, z.ZodObject<{
+      in: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+    }, z.core.$strict>, z.ZodObject<{
+      notIn: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+    }, z.core.$strict>, z.ZodObject<{
+      isNull: z.ZodLiteral<true>;
+    }, z.core.$strict>, z.ZodObject<{
+      isNotNull: z.ZodLiteral<true>;
+    }, z.core.$strict>]>]>>]>>;
+    fields: z.ZodRecord<z.ZodString, z.ZodString>;
+    readOnly: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    relationships: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+      entity: z.ZodString;
+      via: z.ZodUnion<readonly [z.ZodObject<{
+        fkOn: z.ZodEnum<{
+          contact: "contact";
+          company: "company";
+        }>;
+        column: z.ZodString;
+      }, z.core.$strict>, z.ZodObject<{
+        through: z.ZodString;
+        localKey: z.ZodString;
+        foreignKey: z.ZodString;
+      }, z.core.$strict>, z.ZodObject<{
+        $raw: z.ZodString;
+      }, z.core.$strict>]>;
+    }, z.core.$strict>>>;
+  }, z.core.$strict>>;
+}, z.core.$strict>;
+type ClivlyEntitiesConfig = z.infer<typeof entitiesConfigSchema>;
+/**
+ * Structural helper for `clivly.config.ts`. Gives full type inference on the
+ * literal you pass and eagerly parses it, so shape errors surface at config
+ * load rather than at sync time. Does NOT validate against the host schema —
+ * that needs the discovered schema; see `validateEntitiesConfig`.
+ */
+declare function defineClivlyConfig(config: ClivlyEntitiesConfig): ClivlyEntitiesConfig;
+/**
+ * A host table the SDK reported for discovery. Structurally identical to the
+ * SDK's `DiscoveredTable`; duplicated here to keep `@clivly/core` free of an
+ * SDK dependency (core is the base contract SDK builds on).
+ */
+interface DiscoveredSchemaTable {
+  columns: string[];
+  name: string;
+}
+interface ConfigValidationError {
+  message: string;
+  /** Dotted path into the config, e.g. `entities.owner.fields.email`. */
+  path: string;
+}
+interface ConfigValidationResult {
+  errors: ConfigValidationError[];
+  valid: boolean;
+}
+/**
+ * Validate a (structurally valid) config against the host's discovered schema:
+ * source tables exist, mapped columns exist, `readOnly` ⊆ `fields`, filter
+ * columns exist, and relationships point at real entities/tables/columns.
+ *
+ * `$raw` filters and `$raw` relationship joins are opaque and skipped. Returns
+ * every error found (not just the first) so a mapping UI or CLI can show them
+ * all at once.
+ */
+declare function validateEntitiesConfig(config: ClivlyEntitiesConfig, schema: DiscoveredSchemaTable[]): ConfigValidationResult;
+//#endregion
+export { CANONICAL_FIELDS, CRM_CONCEPTS, ClivlyEntitiesConfig, ClivlyEntityConfig, ConfigValidationError, ConfigValidationResult, CrmConcept, DiscoveredSchemaTable, FilterExpr, FilterValue, RelationshipSpec, RelationshipVia, RelationshipsMap, defineClivlyConfig, entitiesConfigSchema, filterSchema, relationshipSchema, relationshipsSchema, validateEntitiesConfig };

package/dist/entity-config.mjs

@@ -0,0 +1,266 @@
+import { z } from "zod";
+//#region src/entity-config.ts
+/**
+* Entity Config v2 — the declarative contract that turns Clivly's "schema-aware"
+* promise into a real capability.
+*
+* A CRM entity is no longer a flat table name. It is a *derived entity*: a
+* filtered slice of a host table (`source` + `filter`), a column allowlist
+* (`fields` + `readOnly`), and declared `relationships` to other entities. The
+* same host table can back several entities (e.g. `users` → owners + members)
+* distinguished by `role`.
+*
+* This module is the Phase 1 slice: types, schema, `defineClivlyConfig` (a
+* structural helper) and `validateEntitiesConfig` (semantic validation against
+* the host's discovered schema). It performs NO DB access and generates no SQL —
+* the view compiler (Phase 2) and sync engine (Phase 3) consume this contract.
+*/
+/** Canonical CRM concepts a host entity can map onto. */
+const CRM_CONCEPTS = [
+	"contact",
+	"company",
+	"deal",
+	"activity",
+	"conversation",
+	"note"
+];
+/**
+* The canonical `fields` keys the mirror actually persists, per concept — the
+* crm_* columns the sync store writes. An entity's `fields` map keys must be one
+* of these: a non-canonical key (e.g. `fullName` instead of `name`) validates
+* structurally but has no destination column, so the store silently writes an
+* empty value. `validateEntitiesConfig` flags those.
+*
+* This is the single source of truth — the Drizzle store imports it, so the
+* two can't drift (the drift is what made the silent-data-loss trap possible).
+* Concepts absent here aren't materialized yet, so their field keys are
+* unconstrained.
+*/
+const CANONICAL_FIELDS = {
+	contact: [
+		"name",
+		"email",
+		"title",
+		"status"
+	],
+	company: [
+		"name",
+		"domain",
+		"industry",
+		"size"
+	]
+};
+/**
+* Operator forms for a single column predicate. All predicates on an entity are
+* AND-ed together. `$raw` (see FilterExpr) is the escape hatch for anything the
+* operators can't express.
+*/
+const filterOperatorsSchema = z.union([
+	z.strictObject({ eq: z.union([
+		z.string(),
+		z.number(),
+		z.boolean()
+	]) }),
+	z.strictObject({ ne: z.union([
+		z.string(),
+		z.number(),
+		z.boolean()
+	]) }),
+	z.strictObject({ in: z.array(z.union([
+		z.string(),
+		z.number(),
+		z.boolean()
+	])).min(1) }),
+	z.strictObject({ notIn: z.array(z.union([
+		z.string(),
+		z.number(),
+		z.boolean()
+	])).min(1) }),
+	z.strictObject({ isNull: z.literal(true) }),
+	z.strictObject({ isNotNull: z.literal(true) })
+]);
+const filterValueSchema = z.union([
+	z.string(),
+	z.number(),
+	z.boolean(),
+	filterOperatorsSchema
+]);
+/**
+* A raw SQL predicate fragment. Kept as a *string* (not a query-builder callback)
+* so the whole config stays JSON-serializable — it can be persisted into
+* `crm_entity_mappings` and shipped to the cloud unchanged. Embedded-only in
+* practice; not validated against the schema.
+*/
+const rawFilterSchema = z.strictObject({ $raw: z.string().min(1) });
+const columnFilterSchema = z.record(z.string(), filterValueSchema);
+/** `$raw` is a reserved key; a column literally named `$raw` is not addressable. */
+const filterSchema = z.union([rawFilterSchema, columnFilterSchema]);
+/**
+* How the link between two entities is expressed in the host schema:
+* - `fkOn: "company"` — FK lives on the company table (e.g. organizations.owner_id)
+* - `fkOn: "contact"` — FK lives on the contact table (e.g. users.organization_id)
+* - `through`         — a join table sits between them (many-to-many, role often here)
+* - `$raw`            — opaque SQL join fragment (escape hatch; not schema-validated)
+*
+* `column` and the join-table keys are `table.column` or bare `column` strings.
+*/
+const relationshipViaSchema = z.union([
+	z.strictObject({
+		fkOn: z.enum(["company", "contact"]),
+		column: z.string().min(1)
+	}),
+	z.strictObject({
+		through: z.string().min(1),
+		localKey: z.string().min(1),
+		foreignKey: z.string().min(1)
+	}),
+	z.strictObject({ $raw: z.string().min(1) })
+]);
+const relationshipSchema = z.strictObject({
+	/** Key of the related entity in the `entities` map. */
+	entity: z.string().min(1),
+	via: relationshipViaSchema
+});
+/** A named map of relationships, as stored on an entity / in the mappings row. */
+const relationshipsSchema = z.record(z.string(), relationshipSchema);
+const entitySchema = z.strictObject({
+	/** Which CRM concept this entity maps onto. */
+	concept: z.enum(CRM_CONCEPTS),
+	/** Host table (or view) this entity is derived from. */
+	source: z.string().min(1),
+	/**
+	* Distinguishes multiple entities backed by the same table (e.g. "primary"
+	* for owners, "secondary" for members). Free text; defaults to "primary".
+	*/
+	role: z.string().min(1).optional(),
+	/** Predicate that narrows `source` into this entity's rows. Omit = whole table. */
+	filter: filterSchema.optional(),
+	/** clivlyField → sourceColumn. At least one field is required. */
+	fields: z.record(z.string(), z.string()).refine((f) => Object.keys(f).length > 0, { message: "at least one field must be mapped" }),
+	/**
+	* Host-owned identity fields. Sync overwrites them; the CRM UI cannot edit
+	* them. Must be a subset of `fields` keys.
+	*/
+	readOnly: z.array(z.string()).optional(),
+	/** Named relationships to other entities in this config. */
+	relationships: z.record(z.string(), relationshipSchema).optional()
+});
+const entitiesConfigSchema = z.strictObject({ entities: z.record(z.string(), entitySchema).refine((e) => Object.keys(e).length > 0, { message: "at least one entity must be defined" }) });
+/**
+* Structural helper for `clivly.config.ts`. Gives full type inference on the
+* literal you pass and eagerly parses it, so shape errors surface at config
+* load rather than at sync time. Does NOT validate against the host schema —
+* that needs the discovered schema; see `validateEntitiesConfig`.
+*/
+function defineClivlyConfig(config) {
+	return entitiesConfigSchema.parse(config);
+}
+/** Split a `table.column` / bare `column` ref into its parts. */
+function parseColumnRef(ref) {
+	const dot = ref.indexOf(".");
+	if (dot === -1) return { column: ref };
+	return {
+		table: ref.slice(0, dot),
+		column: ref.slice(dot + 1)
+	};
+}
+/** Shared lookup + error-collection state threaded through the validators. */
+var SchemaValidator = class {
+	errors = [];
+	columnsByTable = /* @__PURE__ */ new Map();
+	constructor(schema) {
+		for (const table of schema) this.columnsByTable.set(table.name, new Set(table.columns));
+	}
+	tableExists(name) {
+		return this.columnsByTable.has(name);
+	}
+	columnExists(table, column) {
+		return this.columnsByTable.get(table)?.has(column) ?? false;
+	}
+	report(path, message) {
+		this.errors.push({
+			path,
+			message
+		});
+	}
+	/** Report if `column` is absent from `table`. Returns whether it existed. */
+	requireColumn(path, table, column) {
+		if (this.columnExists(table, column)) return true;
+		this.report(path, `column "${column}" does not exist on "${table}"`);
+		return false;
+	}
+};
+function validateFields(v, base, entity) {
+	const canonical = CANONICAL_FIELDS[entity.concept];
+	for (const [field, column] of Object.entries(entity.fields)) {
+		v.requireColumn(`${base}.fields.${field}`, entity.source, column);
+		if (canonical && !canonical.includes(field)) v.report(`${base}.fields.${field}`, `"${field}" is not a canonical ${entity.concept} field (expected one of: ${canonical.join(", ")})`);
+	}
+}
+function validateReadOnly(v, base, entity) {
+	for (const field of entity.readOnly ?? []) if (!(field in entity.fields)) v.report(`${base}.readOnly`, `"${field}" is not one of this entity's fields`);
+}
+function validateFilter(v, base, entity) {
+	if (!entity.filter || "$raw" in entity.filter) return;
+	for (const column of Object.keys(entity.filter)) v.requireColumn(`${base}.filter.${column}`, entity.source, column);
+}
+function validateFkVia(v, relBase, via, entity, related) {
+	const { table, column } = parseColumnRef(via.column);
+	const fkTable = table ?? (via.fkOn === "contact" ? entity.source : related?.source);
+	const path = `${relBase}.via.column`;
+	if (!fkTable) {
+		v.report(path, `cannot resolve table for FK column "${via.column}"`);
+		return;
+	}
+	if (!v.tableExists(fkTable)) {
+		v.report(path, `table "${fkTable}" is not in the discovered schema`);
+		return;
+	}
+	v.requireColumn(path, fkTable, column);
+}
+function validateThroughVia(v, relBase, via) {
+	if (!v.tableExists(via.through)) {
+		v.report(`${relBase}.via.through`, `join table "${via.through}" is not in the discovered schema`);
+		return;
+	}
+	v.requireColumn(`${relBase}.via.localKey`, via.through, via.localKey);
+	v.requireColumn(`${relBase}.via.foreignKey`, via.through, via.foreignKey);
+}
+function validateRelationship(v, base, config, entity, relName, rel) {
+	const relBase = `${base}.relationships.${relName}`;
+	const related = config.entities[rel.entity];
+	if (!related) v.report(`${relBase}.entity`, `"${rel.entity}" is not a defined entity`);
+	const { via } = rel;
+	if ("fkOn" in via) validateFkVia(v, relBase, via, entity, related);
+	else if ("through" in via) validateThroughVia(v, relBase, via);
+}
+function validateEntity(v, config, key, entity) {
+	const base = `entities.${key}`;
+	if (!v.tableExists(entity.source)) {
+		v.report(`${base}.source`, `table "${entity.source}" is not in the discovered schema`);
+		return;
+	}
+	validateFields(v, base, entity);
+	validateReadOnly(v, base, entity);
+	validateFilter(v, base, entity);
+	for (const [relName, rel] of Object.entries(entity.relationships ?? {})) validateRelationship(v, base, config, entity, relName, rel);
+}
+/**
+* Validate a (structurally valid) config against the host's discovered schema:
+* source tables exist, mapped columns exist, `readOnly` ⊆ `fields`, filter
+* columns exist, and relationships point at real entities/tables/columns.
+*
+* `$raw` filters and `$raw` relationship joins are opaque and skipped. Returns
+* every error found (not just the first) so a mapping UI or CLI can show them
+* all at once.
+*/
+function validateEntitiesConfig(config, schema) {
+	const validator = new SchemaValidator(schema);
+	for (const [key, entity] of Object.entries(config.entities)) validateEntity(validator, config, key, entity);
+	return {
+		valid: validator.errors.length === 0,
+		errors: validator.errors
+	};
+}
+//#endregion
+export { CANONICAL_FIELDS, CRM_CONCEPTS, defineClivlyConfig, entitiesConfigSchema, filterSchema, relationshipSchema, relationshipsSchema, validateEntitiesConfig };

package/dist/index.d.mts

@@ -0,0 +1,9 @@
+import { Activity, ActivityType, Company, Contact, ContactFilters, ContactStatus, CreateActivityInput, CreateCompanyInput, CreateContactInput, CreateDealInput, CreateTaskInput, CrmRole, Deal, DealStage, Note, Task, TaskEntityType, TaskFilters, TaskPriority, TaskStatus, UpdateContactInput, UpdateTaskInput } from "./types.mjs";
+import { CRMAdapter } from "./adapter.mjs";
+import { ClivlyAuthAdapter, ClivlyUser, CrmMembership, MembershipResolver, authCustom } from "./auth-adapter.mjs";
+import { CANONICAL_FIELDS, CRM_CONCEPTS, ClivlyEntitiesConfig, ClivlyEntityConfig, ConfigValidationError, ConfigValidationResult, CrmConcept, DiscoveredSchemaTable, FilterExpr, FilterValue, RelationshipSpec, RelationshipVia, RelationshipsMap, defineClivlyConfig, entitiesConfigSchema, filterSchema, relationshipSchema, relationshipsSchema, validateEntitiesConfig } from "./entity-config.mjs";
+import { RelationshipCandidate, buildFilterFromDiscriminator, buildRelationships, relationshipViaSignature } from "./mapping-form.mjs";
+import { EntityMappingRow, mappingsToEntitiesConfig } from "./mappings-config.mjs";
+import { CompileOptions, CompiledView, compileEntityView, compileEntityViews } from "./view-compiler.mjs";
+import { EntitySyncResult, MirrorRecord, PersistAction, SourceRow, SyncAction, SyncResult, SyncStore, reconcile, runSync } from "./sync-engine.mjs";
+export { Activity, ActivityType, CANONICAL_FIELDS, type CRMAdapter, CRM_CONCEPTS, type ClivlyAuthAdapter, type ClivlyEntitiesConfig, type ClivlyEntityConfig, type ClivlyUser, Company, type CompileOptions, type CompiledView, type ConfigValidationError, type ConfigValidationResult, Contact, ContactFilters, ContactStatus, CreateActivityInput, CreateCompanyInput, CreateContactInput, CreateDealInput, CreateTaskInput, type CrmConcept, type CrmMembership, CrmRole, Deal, DealStage, type DiscoveredSchemaTable, type EntityMappingRow, type EntitySyncResult, type FilterExpr, type FilterValue, type MembershipResolver, type MirrorRecord, Note, type PersistAction, type RelationshipCandidate, type RelationshipSpec, type RelationshipVia, type RelationshipsMap, type SourceRow, type SyncAction, type SyncResult, type SyncStore, Task, TaskEntityType, TaskFilters, TaskPriority, TaskStatus, UpdateContactInput, UpdateTaskInput, authCustom, buildFilterFromDiscriminator, buildRelationships, compileEntityView, compileEntityViews, defineClivlyConfig, entitiesConfigSchema, filterSchema, mappingsToEntitiesConfig, reconcile, relationshipSchema, relationshipViaSignature, relationshipsSchema, runSync, validateEntitiesConfig };

package/dist/index.mjs

@@ -0,0 +1,7 @@
+import { authCustom } from "./auth-adapter.mjs";
+import { CANONICAL_FIELDS, CRM_CONCEPTS, defineClivlyConfig, entitiesConfigSchema, filterSchema, relationshipSchema, relationshipsSchema, validateEntitiesConfig } from "./entity-config.mjs";
+import { buildFilterFromDiscriminator, buildRelationships, relationshipViaSignature } from "./mapping-form.mjs";
+import { mappingsToEntitiesConfig } from "./mappings-config.mjs";
+import { compileEntityView, compileEntityViews } from "./view-compiler.mjs";
+import { reconcile, runSync } from "./sync-engine.mjs";
+export { CANONICAL_FIELDS, CRM_CONCEPTS, authCustom, buildFilterFromDiscriminator, buildRelationships, compileEntityView, compileEntityViews, defineClivlyConfig, entitiesConfigSchema, filterSchema, mappingsToEntitiesConfig, reconcile, relationshipSchema, relationshipViaSignature, relationshipsSchema, runSync, validateEntitiesConfig };