clivly 0.9.0 → 0.9.2

package/{entity-config-C4Yf_fPj.d.mts → entity-config-B2RA53nw.d.mts}

@@ -2120,6 +2120,126 @@ interface ZodReadonly<T extends SomeType = $ZodType> extends _ZodType<$ZodReadon
 }
 declare const ZodReadonly: $constructor<ZodReadonly>;
 //#endregion
+//#region ../core/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: ZodObject<{
+  table: ZodString;
+  column: ZodString;
+}, $strict>;
+type ProjectionRef = output<typeof projectionRefSchema>;
+declare const projectionJoinSchema: ZodObject<{
+  key: ZodString;
+  table: ZodString;
+  type: ZodEnum<{
+    inner: "inner";
+    left: "left";
+  }>;
+  on: ZodArray<ZodObject<{
+    left: ZodObject<{
+      table: ZodString;
+      column: ZodString;
+    }, $strict>;
+    op: ZodLiteral<"eq">;
+    right: ZodObject<{
+      table: ZodString;
+      column: ZodString;
+    }, $strict>;
+  }, $strict>>;
+}, $strict>;
+type ProjectionJoin = output<typeof projectionJoinSchema>;
+declare const projectionFieldBindingSchema: ZodObject<{
+  from: ZodObject<{
+    table: ZodString;
+    column: ZodString;
+  }, $strict>;
+}, $strict>;
+type ProjectionFieldBinding = output<typeof projectionFieldBindingSchema>;
+declare const projectionIdentitySchema: ZodUnion<readonly [ZodObject<{
+  kind: ZodLiteral<"base_pk">;
+  column: ZodOptional<ZodString>;
+}, $strict>, ZodObject<{
+  kind: ZodLiteral<"column">;
+  from: ZodObject<{
+    table: ZodString;
+    column: ZodString;
+  }, $strict>;
+}, $strict>, ZodObject<{
+  kind: ZodLiteral<"composite">;
+  parts: ZodArray<ZodObject<{
+    table: ZodString;
+    column: ZodString;
+  }, $strict>>;
+}, $strict>]>;
+type ProjectionIdentity = output<typeof projectionIdentitySchema>;
+declare const projectionSchema: ZodObject<{
+  version: ZodLiteral<1>;
+  kind: ZodLiteral<"projection">;
+  entityKey: ZodString;
+  baseTable: ZodString;
+  joins: ZodArray<ZodObject<{
+    key: ZodString;
+    table: ZodString;
+    type: ZodEnum<{
+      inner: "inner";
+      left: "left";
+    }>;
+    on: ZodArray<ZodObject<{
+      left: ZodObject<{
+        table: ZodString;
+        column: ZodString;
+      }, $strict>;
+      op: ZodLiteral<"eq">;
+      right: ZodObject<{
+        table: ZodString;
+        column: ZodString;
+      }, $strict>;
+    }, $strict>>;
+  }, $strict>>;
+  fieldBindings: ZodRecord<ZodString, ZodObject<{
+    from: ZodObject<{
+      table: ZodString;
+      column: ZodString;
+    }, $strict>;
+  }, $strict>>;
+  identity: ZodUnion<readonly [ZodObject<{
+    kind: ZodLiteral<"base_pk">;
+    column: ZodOptional<ZodString>;
+  }, $strict>, ZodObject<{
+    kind: ZodLiteral<"column">;
+    from: ZodObject<{
+      table: ZodString;
+      column: ZodString;
+    }, $strict>;
+  }, $strict>, ZodObject<{
+    kind: ZodLiteral<"composite">;
+    parts: ZodArray<ZodObject<{
+      table: ZodString;
+      column: ZodString;
+    }, $strict>>;
+  }, $strict>]>;
+}, $strict>;
+type ProjectionMapping = output<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 ../core/src/entity-config.d.ts
 /**
  * Entity Config v2 — the declarative contract that turns Clivly's "schema-aware"
@@ -2312,6 +2432,11 @@ declare const entitySchema: ZodObject<{
     }, $strict>]>;
   }, $strict>>>;
   targetObjectTypeId: ZodOptional<ZodString>;
+  objectType: ZodOptional<ZodObject<{
+    name: ZodString;
+    pluralName: ZodOptional<ZodString>;
+    iconKey: ZodOptional<ZodString>;
+  }, $strict>>;
   projection: ZodOptional<ZodObject<{
     version: ZodLiteral<1>;
     kind: ZodLiteral<"projection">;
@@ -2407,6 +2532,11 @@ declare const entitiesConfigSchema: ZodObject<{
       }, $strict>]>;
     }, $strict>>>;
     targetObjectTypeId: ZodOptional<ZodString>;
+    objectType: ZodOptional<ZodObject<{
+      name: ZodString;
+      pluralName: ZodOptional<ZodString>;
+      iconKey: ZodOptional<ZodString>;
+    }, $strict>>;
     projection: ZodOptional<ZodObject<{
       version: ZodLiteral<1>;
       kind: ZodLiteral<"projection">;
@@ -2457,6 +2587,21 @@ declare const entitiesConfigSchema: ZodObject<{
   }, $strict>>;
 }, $strict>;
 type ClivlyEntitiesConfig = output<typeof entitiesConfigSchema>;
+/**
+ * What an author may hand to `defineClivlyConfig`. Identical to
+ * `ClivlyEntityConfig` except that a projection entity may omit `fields` —
+ * it is derived from `projection.fieldBindings`. Without a projection `fields`
+ * stays required, so the looser input never weakens the ordinary case.
+ */
+type ClivlyEntityConfigInput = (ClivlyEntityConfig & {
+  projection?: undefined;
+}) | (Omit<ClivlyEntityConfig, "fields"> & {
+  fields?: Record<string, string>;
+  projection: ProjectionMapping;
+});
+type ClivlyEntitiesConfigInput = Omit<ClivlyEntitiesConfig, "entities"> & {
+  entities: Record<string, ClivlyEntityConfigInput>;
+};
 /** Thrown by `defineClivlyConfig({ strict: true })` on non-canonical field keys. */
 declare class ClivlyConfigError extends Error {
   readonly issues: ConfigValidationError[];
@@ -2474,7 +2619,28 @@ declare class ClivlyConfigError extends Error {
  * a `ClivlyConfigError` instead. Does NOT validate against the host schema — that
  * needs the discovered schema; see `validateEntitiesConfig`.
  */
-declare function defineClivlyConfig(config: ClivlyEntitiesConfig, options?: {
+/** A custom object the host declares in config, for `push-schema` to ensure. */
+interface CustomObjectDeclaration {
+  iconKey?: string;
+  name: string;
+  pluralName?: string;
+  /** Unique per org and immutable — the entity key. */
+  slug: string;
+}
+/**
+ * The custom objects a config declares, keyed by entity slug. Entities that
+ * already carry an explicit `targetObjectTypeId` are omitted: their object type
+ * exists server-side and re-declaring it would be a no-op at best.
+ */
+declare function customObjectDeclarations(config: ClivlyEntitiesConfig): CustomObjectDeclaration[];
+/**
+ * The `fields` entry a projection binding implies, qualified as `ref.column`.
+ * Qualified rather than bare: two bindings can pull the same column name from
+ * different tables (`cl.full_name` and `adv.full_name`), which a bare column
+ * name cannot tell apart.
+ */
+declare function projectionFields(projection: ProjectionMapping): Record<string, string>;
+declare function defineClivlyConfig(config: ClivlyEntitiesConfigInput, options?: {
   strict?: boolean;
   onWarn?: (message: string) => void;
 }): ClivlyEntitiesConfig;
@@ -2532,4 +2698,4 @@ interface ConfigValidationResult {
  */
 declare function validateEntitiesConfig(config: ClivlyEntitiesConfig, schema: DiscoveredSchemaTable[]): ConfigValidationResult;
 //#endregion
-export { ZodRecord as A, relationshipsSchema as C, ZodLiteral as D, ZodEnum as E, ZodUnion as M, output as N, ZodObject as O, $strict as P, relationshipSchema as S, ZodArray as T, RelationshipVia as _, ClivlyEntitiesConfig as a, entitiesConfigSchema as b, ConfigValidationResult as c, DiscoveredSchemaTable as d, FilterExpr as f, RelationshipSpec as g, MaterializingConcept as h, ClivlyConfigError as i, ZodString as j, ZodOptional as k, CrmConcept as l, MATERIALIZING_CONCEPTS as m, CRM_CONCEPTS as n, ClivlyEntityConfig as o, FilterValue as p, CUSTOM_CONCEPT as r, ConfigValidationError as s, CANONICAL_FIELDS as t, DiscoveredColumnMeta as u, RelationshipsMap as v, validateEntitiesConfig as w, filterSchema as x, defineClivlyConfig as y };
+export { BASE_REF as A, defineClivlyConfig as C, relationshipSchema as D, projectionFields as E, ProjectionRef as F, identityRefs as I, projectionSchema as L, ProjectionIdentity as M, ProjectionJoin as N, relationshipsSchema as O, ProjectionMapping as P, customObjectDeclarations as S, filterSchema as T, MATERIALIZING_CONCEPTS as _, ClivlyEntitiesConfig as a, RelationshipVia as b, ClivlyEntityConfigInput as c, CrmConcept as d, CustomObjectDeclaration as f, FilterValue as g, FilterExpr as h, ClivlyConfigError as i, ProjectionFieldBinding as j, validateEntitiesConfig as k, ConfigValidationError as l, DiscoveredSchemaTable as m, CRM_CONCEPTS as n, ClivlyEntitiesConfigInput as o, DiscoveredColumnMeta as p, CUSTOM_CONCEPT as r, ClivlyEntityConfig as s, CANONICAL_FIELDS as t, ConfigValidationResult as u, MaterializingConcept as v, entitiesConfigSchema as w, RelationshipsMap as x, RelationshipSpec as y };

package/{entity-config-CsLl-ftC.cjs → entity-config-DtBsl2MQ.cjs}

@@ -437,10 +437,23 @@ const entitySchema = require_projection.strictObject({
 	relationships: require_projection.record(require_projection.string(), relationshipSchema).optional(),
 	/**
 	* For a "custom" entity, the crm_object_types row this materializes into.
-	* Required for custom (enforced at the API layer), unused for standard concepts.
+	* Server-generated, so pasting one into config couples the file to a
+	* specific workspace. Prefer declaring `objectType` and letting
+	* `clivly push-schema` resolve the id by slug.
 	*/
 	targetObjectTypeId: require_projection.string().min(1).optional(),
 	/**
+	* Declares the custom object this entity materializes into, so config is
+	* self-contained: the entity key is the slug (unique per org and immutable),
+	* and `clivly push-schema` creates the object type if the workspace does not
+	* have it yet. An alternative to pasting a `targetObjectTypeId`.
+	*/
+	objectType: require_projection.strictObject({
+		name: require_projection.string().min(1),
+		pluralName: require_projection.string().min(1).optional(),
+		iconKey: require_projection.string().min(1).optional()
+	}).optional(),
+	/**
 	* Advanced mapping: derive this entity from a base table plus explicit joins
 	* instead of a single source table. Valid only for `concept: "custom"`.
 	*
@@ -482,19 +495,69 @@ function defaultWarn(message) {
 	console.warn(message);
 }
 /**
-* 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.
-*
-* It also catches the silent-data-loss footgun: a non-canonical field key for a
-* materialised concept (e.g. `fullName` instead of `name` on a `contact`) has no
-* destination column, so the store would write an empty value. By default these
-* are reported via `onWarn` (a `console.warn`); pass `{ strict: true }` to throw
-* a `ClivlyConfigError` instead. Does NOT validate against the host schema — that
-* needs the discovered schema; see `validateEntitiesConfig`.
+* The custom objects a config declares, keyed by entity slug. Entities that
+* already carry an explicit `targetObjectTypeId` are omitted: their object type
+* exists server-side and re-declaring it would be a no-op at best.
+*/
+function customObjectDeclarations(config) {
+	const declarations = [];
+	for (const [slug, entity] of Object.entries(config.entities)) {
+		if (entity.concept !== "custom" || entity.targetObjectTypeId) continue;
+		if (!entity.objectType) continue;
+		declarations.push({
+			slug,
+			...entity.objectType
+		});
+	}
+	return declarations;
+}
+/**
+* The `fields` entry a projection binding implies, qualified as `ref.column`.
+* Qualified rather than bare: two bindings can pull the same column name from
+* different tables (`cl.full_name` and `adv.full_name`), which a bare column
+* name cannot tell apart.
+*/
+function projectionFields(projection) {
+	const fields = {};
+	for (const [name, binding] of Object.entries(projection.fieldBindings)) fields[name] = `${binding.from.table}.${binding.from.column}`;
+	return fields;
+}
+/**
+* `fields` duplicates `projection.fieldBindings`, and only the bindings are
+* compiled — so a hand-written `fields` that drifts is both silent and
+* invisible. Derive it when omitted, and reject it when it disagrees.
 */
+function normalizeProjectionFields(config) {
+	const entities = {};
+	for (const [key, entity] of Object.entries(config.entities ?? {})) {
+		const projection = entity?.projection;
+		if (!projection?.fieldBindings) {
+			entities[key] = entity;
+			continue;
+		}
+		const derived = projectionFields(projection);
+		const declared = entity.fields;
+		if (!declared) {
+			entities[key] = {
+				...entity,
+				fields: derived
+			};
+			continue;
+		}
+		const drifted = [.../* @__PURE__ */ new Set([...Object.keys(derived), ...Object.keys(declared)])].filter((name) => declared[name] !== derived[name]).sort();
+		if (drifted.length > 0) {
+			const detail = drifted.map((name) => `"${name}": fields has ${declared[name] === void 0 ? "no entry" : `"${declared[name]}"`}, bindings imply ${derived[name] === void 0 ? "no entry" : `"${derived[name]}"`}`).join("; ");
+			throw new Error(`Clivly config: entity "${key}" has a \`fields\` map that disagrees with \`projection.fieldBindings\` — ${detail}. Only the bindings are compiled, so the \`fields\` copy would be silently ignored. Omit \`fields\` entirely and it will be derived.`);
+		}
+		entities[key] = entity;
+	}
+	return {
+		...config,
+		entities
+	};
+}
 function defineClivlyConfig(config, options) {
-	const parsed = entitiesConfigSchema.parse(config);
+	const parsed = entitiesConfigSchema.parse(normalizeProjectionFields(config));
 	const issues = canonicalFieldIssues(parsed);
 	if (issues.length > 0) {
 		if (options?.strict) throw new ClivlyConfigError(issues);
@@ -587,7 +650,7 @@ function validateEntity(v, config, key, entity, schema) {
 	}
 	if (entity.projection) {
 		if (entity.concept !== "custom") v.report(`${base}.projection`, `projection mappings are only supported for concept "${CUSTOM_CONCEPT}"`);
-		if (!entity.targetObjectTypeId) v.report(`${base}.targetObjectTypeId`, "a projection mapping must target a custom object type");
+		if (!(entity.targetObjectTypeId || entity.objectType)) v.report(`${base}.targetObjectTypeId`, "a projection mapping must target a custom object type — declare `objectType: { name: \"…\" }` (recommended: the entity key becomes its slug) or set an explicit `targetObjectTypeId`");
 		if (entity.source !== entity.projection.baseTable) v.report(`${base}.source`, `"source" ("${entity.source}") must match "projection.baseTable" ("${entity.projection.baseTable}") — the view compiler reads baseTable and the sync engine reads source, so a mismatch makes them disagree about which table this entity is`);
 		for (const error of validateProjection(entity.projection, schema, base)) v.report(error.path, error.message);
 		validateReadOnly(v, base, entity);
@@ -659,6 +722,12 @@ Object.defineProperty(exports, "coversUniqueKey", {
 		return coversUniqueKey;
 	}
 });
+Object.defineProperty(exports, "customObjectDeclarations", {
+	enumerable: true,
+	get: function() {
+		return customObjectDeclarations;
+	}
+});
 Object.defineProperty(exports, "defineClivlyConfig", {
 	enumerable: true,
 	get: function() {
@@ -701,6 +770,12 @@ Object.defineProperty(exports, "primaryKeyColumns", {
 		return primaryKeyColumns;
 	}
 });
+Object.defineProperty(exports, "projectionFields", {
+	enumerable: true,
+	get: function() {
+		return projectionFields;
+	}
+});
 Object.defineProperty(exports, "relationshipSchema", {
 	enumerable: true,
 	get: function() {

package/{entity-config-D3LmzgLb.mjs → entity-config-kUHri9yA.mjs}

@@ -429,10 +429,23 @@ const entitySchema = strictObject({
 	relationships: record(string(), relationshipSchema).optional(),
 	/**
 	* For a "custom" entity, the crm_object_types row this materializes into.
-	* Required for custom (enforced at the API layer), unused for standard concepts.
+	* Server-generated, so pasting one into config couples the file to a
+	* specific workspace. Prefer declaring `objectType` and letting
+	* `clivly push-schema` resolve the id by slug.
 	*/
 	targetObjectTypeId: string().min(1).optional(),
 	/**
+	* Declares the custom object this entity materializes into, so config is
+	* self-contained: the entity key is the slug (unique per org and immutable),
+	* and `clivly push-schema` creates the object type if the workspace does not
+	* have it yet. An alternative to pasting a `targetObjectTypeId`.
+	*/
+	objectType: strictObject({
+		name: string().min(1),
+		pluralName: string().min(1).optional(),
+		iconKey: string().min(1).optional()
+	}).optional(),
+	/**
 	* Advanced mapping: derive this entity from a base table plus explicit joins
 	* instead of a single source table. Valid only for `concept: "custom"`.
 	*
@@ -474,19 +487,69 @@ function defaultWarn(message) {
 	console.warn(message);
 }
 /**
-* 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.
-*
-* It also catches the silent-data-loss footgun: a non-canonical field key for a
-* materialised concept (e.g. `fullName` instead of `name` on a `contact`) has no
-* destination column, so the store would write an empty value. By default these
-* are reported via `onWarn` (a `console.warn`); pass `{ strict: true }` to throw
-* a `ClivlyConfigError` instead. Does NOT validate against the host schema — that
-* needs the discovered schema; see `validateEntitiesConfig`.
+* The custom objects a config declares, keyed by entity slug. Entities that
+* already carry an explicit `targetObjectTypeId` are omitted: their object type
+* exists server-side and re-declaring it would be a no-op at best.
+*/
+function customObjectDeclarations(config) {
+	const declarations = [];
+	for (const [slug, entity] of Object.entries(config.entities)) {
+		if (entity.concept !== "custom" || entity.targetObjectTypeId) continue;
+		if (!entity.objectType) continue;
+		declarations.push({
+			slug,
+			...entity.objectType
+		});
+	}
+	return declarations;
+}
+/**
+* The `fields` entry a projection binding implies, qualified as `ref.column`.
+* Qualified rather than bare: two bindings can pull the same column name from
+* different tables (`cl.full_name` and `adv.full_name`), which a bare column
+* name cannot tell apart.
+*/
+function projectionFields(projection) {
+	const fields = {};
+	for (const [name, binding] of Object.entries(projection.fieldBindings)) fields[name] = `${binding.from.table}.${binding.from.column}`;
+	return fields;
+}
+/**
+* `fields` duplicates `projection.fieldBindings`, and only the bindings are
+* compiled — so a hand-written `fields` that drifts is both silent and
+* invisible. Derive it when omitted, and reject it when it disagrees.
 */
+function normalizeProjectionFields(config) {
+	const entities = {};
+	for (const [key, entity] of Object.entries(config.entities ?? {})) {
+		const projection = entity?.projection;
+		if (!projection?.fieldBindings) {
+			entities[key] = entity;
+			continue;
+		}
+		const derived = projectionFields(projection);
+		const declared = entity.fields;
+		if (!declared) {
+			entities[key] = {
+				...entity,
+				fields: derived
+			};
+			continue;
+		}
+		const drifted = [.../* @__PURE__ */ new Set([...Object.keys(derived), ...Object.keys(declared)])].filter((name) => declared[name] !== derived[name]).sort();
+		if (drifted.length > 0) {
+			const detail = drifted.map((name) => `"${name}": fields has ${declared[name] === void 0 ? "no entry" : `"${declared[name]}"`}, bindings imply ${derived[name] === void 0 ? "no entry" : `"${derived[name]}"`}`).join("; ");
+			throw new Error(`Clivly config: entity "${key}" has a \`fields\` map that disagrees with \`projection.fieldBindings\` — ${detail}. Only the bindings are compiled, so the \`fields\` copy would be silently ignored. Omit \`fields\` entirely and it will be derived.`);
+		}
+		entities[key] = entity;
+	}
+	return {
+		...config,
+		entities
+	};
+}
 function defineClivlyConfig(config, options) {
-	const parsed = entitiesConfigSchema.parse(config);
+	const parsed = entitiesConfigSchema.parse(normalizeProjectionFields(config));
 	const issues = canonicalFieldIssues(parsed);
 	if (issues.length > 0) {
 		if (options?.strict) throw new ClivlyConfigError(issues);
@@ -579,7 +642,7 @@ function validateEntity(v, config, key, entity, schema) {
 	}
 	if (entity.projection) {
 		if (entity.concept !== "custom") v.report(`${base}.projection`, `projection mappings are only supported for concept "${CUSTOM_CONCEPT}"`);
-		if (!entity.targetObjectTypeId) v.report(`${base}.targetObjectTypeId`, "a projection mapping must target a custom object type");
+		if (!(entity.targetObjectTypeId || entity.objectType)) v.report(`${base}.targetObjectTypeId`, "a projection mapping must target a custom object type — declare `objectType: { name: \"…\" }` (recommended: the entity key becomes its slug) or set an explicit `targetObjectTypeId`");
 		if (entity.source !== entity.projection.baseTable) v.report(`${base}.source`, `"source" ("${entity.source}") must match "projection.baseTable" ("${entity.projection.baseTable}") — the view compiler reads baseTable and the sync engine reads source, so a mismatch makes them disagree about which table this entity is`);
 		for (const error of validateProjection(entity.projection, schema, base)) v.report(error.path, error.message);
 		validateReadOnly(v, base, entity);
@@ -609,4 +672,4 @@ function validateEntitiesConfig(config, schema) {
 	};
 }
 //#endregion
-export { hasRichMeta as _, MATERIALIZING_CONCEPTS as a, filterSchema as c, validateEntitiesConfig as d, validateProjection as f, coversUniqueKey as g, columnMetaFor as h, ClivlyConfigError as i, relationshipSchema as l, joinFansOut as m, CRM_CONCEPTS as n, defineClivlyConfig as o, fanOutJoins as p, CUSTOM_CONCEPT as r, entitiesConfigSchema as s, CANONICAL_FIELDS as t, relationshipsSchema as u, primaryKeyColumns as v };
+export { columnMetaFor as _, MATERIALIZING_CONCEPTS as a, primaryKeyColumns as b, entitiesConfigSchema as c, relationshipSchema as d, relationshipsSchema as f, joinFansOut as g, fanOutJoins as h, ClivlyConfigError as i, filterSchema as l, validateProjection as m, CRM_CONCEPTS as n, customObjectDeclarations as o, validateEntitiesConfig as p, CUSTOM_CONCEPT as r, defineClivlyConfig as s, CANONICAL_FIELDS as t, projectionFields as u, coversUniqueKey as v, hasRichMeta as y };