@clivly/core 0.7.0 → 0.7.2

package/README.md

@@ -1,47 +1,77 @@
 # @clivly/core
 
-ORM- and auth-agnostic contracts and shared domain types for [Clivly](https://clivly.com) — the CRM that lives inside your app.
+Contracts and shared helpers for Clivly adapters, config validation, discovery,
+and sync logic.
 
-This package defines the interfaces that ORM and auth adapters implement. It has no runtime dependencies.
+## Who this package is for
 
-## Exports
+Most application integrators should install `clivly` and import from
+`clivly/sdk`.
 
-| 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`) |
-| `@clivly/core/drizzle` | `discoverFromDrizzle(schema)` — derive the discovery shape from a Drizzle schema object. Requires the optional `drizzle-orm` peer dependency |
+`@clivly/core` is the lower-level public package for:
+
+- adapter authors
+- tooling authors
+- consumers who intentionally want the contract and utility layer directly
+
+It has a small runtime surface centered on `zod`. `drizzle-orm` is only needed
+when you use the Drizzle discovery subpath.
 
-## Schema discovery (Drizzle)
+## Install
 
-`discoverFromDrizzle` turns your Drizzle schema into Clivly's discovery shape, so you don't hand-author table/column arrays:
+```bash
+npm install @clivly/core
+```
+
+Optional Drizzle integration:
+
+```bash
+npm install @clivly/core drizzle-orm
+```
+
+## Exports
+
+| Entry | Contents |
+| --- | --- |
+| `@clivly/core` | Re-exports the package surface |
+| `@clivly/core/adapter` | `CRMAdapter` |
+| `@clivly/core/auth-adapter` | `ClivlyAuthAdapter`, `authCustom()`, `MembershipResolver` |
+| `@clivly/core/types` | Shared CRM types and inputs |
+| `@clivly/core/drizzle` | `discoverFromDrizzle(schema)` |
+| `@clivly/core/entity-config` | `defineClivlyConfig`, validators, canonical field metadata |
+| `@clivly/core/view-compiler` | Entity-view compilation helpers |
+| `@clivly/core/sync-engine` | `runSync`, `previewSync`, `reconcile`, `computeSampleWarnings` |
+| `@clivly/core/entity-heuristics` | Concept and mapping inference helpers |
+| `@clivly/core/mapping-score` | Scoring tiers and ambiguity helpers |
+| `@clivly/core/mapping-form` | UI-to-config assembly helpers |
+| `@clivly/core/mappings-config` | Persisted-mapping to entity-config conversion |
+
+## Drizzle schema discovery
 
 ```ts
 import { discoverFromDrizzle } from "@clivly/core/drizzle";
 import * as schema from "./db/schema";
 
 const tables = discoverFromDrizzle(schema);
-// → [{ name: "participants", columns: ["id", "full_name", "email", …] }, …]
 ```
 
-Column names are the real DB names (`full_name`), not the Drizzle keys (`fullName`). `drizzle-orm` is an **optional peer dependency** — only needed when you import this subpath.
+This returns real database column names such as `full_name`, not Drizzle
+property keys such as `fullName`.
 
-## Usage
+## Example: adapter contract
 
 ```ts
-import type { CRMAdapter } from "@clivly/core";
+import type { CRMAdapter } from "@clivly/core/adapter";
 
-// packages/drizzle implements this; Prisma/Kysely can follow.
 function useAdapter(crm: CRMAdapter) {
-  return crm.getContacts(orgId);
+  return crm.getContacts("org_1");
 }
 ```
 
-## The `$raw` escape hatch
+## `$raw` escape hatch
 
-Entity `filter`s and relationship `via`s accept a `$raw` form — an opaque SQL fragment for predicates the operators can't express (e.g. a cross-table condition):
+Entity `filter`s and relationship `via`s accept a `$raw` SQL fragment for cases
+the structured operators cannot express:
 
 ```ts
 defineClivlyConfig({
@@ -56,30 +86,19 @@ defineClivlyConfig({
 });
 ```
 
-**`$raw` is unchecked.** `validateEntitiesConfig` deliberately **skips** `$raw` filters and joins — it can't know your columns are real or your SQL is valid. Two consequences:
+`$raw` is intentionally unchecked:
 
-- **Injection safety is on you.** Never interpolate untrusted input into a `$raw` string; treat it like handwritten SQL. Everything else in the config is escaped for you; `$raw` is not.
-- **Mistakes surface at sync time, not config time** — unless you dry-run it.
+- never interpolate untrusted input into it
+- mistakes surface when the query is exercised, not at config-parse time
 
-### Dry-run with `explainEntitiesConfig`
+Use `explainEntitiesConfig()` to dry-run compiled views before your first sync.
 
-`explainEntitiesConfig(config, run, options?)` compiles each entity's view and executes it via a runner you provide, so a broken `$raw` fragment fails **before** the first sync. It never throws — it returns one `ExplainResult` per entity:
+## More docs
 
-```ts
-import { explainEntitiesConfig } from "@clivly/core";
-
-const results = await explainEntitiesConfig(config, (sql) =>
-  // Run somewhere side-effect-free — e.g. a transaction you roll back.
-  db.transaction(async (tx) => {
-    await tx.execute(sql);
-    throw new Rollback();
-  }).catch(swallowRollback)
-);
-
-for (const r of results) {
-  if (!r.ok) console.error(`${r.entityKey}: ${r.error}`);
-}
-```
+- Stability policy:
+  [STABILITY.md](https://github.com/amani-joseph/clivly.com/blob/master/STABILITY.md)
+- SDK docs:
+  [packages/sdk/README.md](https://github.com/amani-joseph/clivly.com/blob/master/packages/sdk/README.md)
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clivly/core",
-  "version": "0.7.0",
+  "version": "0.7.2",
   "private": false,
   "type": "module",
   "description": "ORM/auth-agnostic CRM adapter contracts and shared domain types for Clivly.",
@@ -138,7 +138,7 @@
     "zod": "^4.1.13"
   },
   "peerDependencies": {
-    "drizzle-orm": ">=0.30"
+    "drizzle-orm": ">=0.30 || >=1.0.0-rc.0"
   },
   "peerDependenciesMeta": {
     "drizzle-orm": {