@clivly/core 0.9.2 → 0.9.4

package/README.md

@@ -35,8 +35,15 @@ npm install @clivly/core
 Every subpath below is importable independently, so you pull in only what you
 use. The root (`.`) re-exports the contracts, entity config, mapping form, sync
 engine and view compiler — but **not** `/drizzle` (which needs the optional
-peer), `/entity-heuristics`, `/mapping-score`, `/integration-state` or
-`/env-file`.
+peer), `/entity-heuristics`, `/mapping-score` or `/env-file`.
+
+`/integration-state` is a deliberate half-exception: the root re-exports its
+**types only** (`IntegrationState`, `IntegrationStep`, `IntegrationFacts`,
+`IntegrationStatus`, `ConnectionLiveness`, `NextAction`, `StepId`, `StepState`,
+`StepProblem`), so a consumer can describe a setup ladder without reaching for
+the subpath. `computeIntegrationState` stays behind `/integration-state`, so
+there is one implementation of the ladder rather than a second one growing in a
+client.
 
 | Entry | Contents |
 | --- | --- |
@@ -47,7 +54,7 @@ peer), `/entity-heuristics`, `/mapping-score`, `/integration-state` or
 | `@clivly/core/types` | Shared domain types (`Contact`, `Company`, `Deal`, `Task`, `Note`, `Activity`, inputs, filters, `CrmRole`) |
 | `@clivly/core/drizzle` | `discoverFromDrizzle(schema)` — derive the discovery shape (including keys, types, nullability and FK edges) from a Drizzle schema object; plus `buildUniqueConstraints` / `buildColumnsMeta` for reflecting a single table. Requires the optional `drizzle-orm` peer |
 | `@clivly/core/view-compiler` | `compileEntityView`, `compileEntityViews`, `explainEntitiesConfig`, `DEFAULT_VIEW_PREFIX` |
-| `@clivly/core/mappings-config` | `mappingsToEntitiesConfig`, `EntityMappingRow` — turn `crm_entity_mappings` rows into an entities config |
+| `@clivly/core/mappings-config` | `mappingsToEntitiesConfig`, `EntityMappingRow` — turn `crm_entity_mappings` rows into an entities config; `entitiesToMappings`, `MappingFromConfig` — the inverse, turning a config into the mapping rows `clivly push-schema` writes |
 | `@clivly/core/mapping-form` | `buildFilterFromDiscriminator`, `buildRelationships`, `relationshipViaSignature` — mapping-UI helpers |
 | `@clivly/core/mapping-score` | Scoring helpers for ranking candidate mappings |
 | `@clivly/core/entity-heuristics` | Table-name heuristics that guess which table holds contacts/companies |

package/dist/{entity-config-DFJ8L9jm.mjs → entity-config-Dt_KfgRl.mjs}

@@ -1,4 +1,4 @@
-import { i as projectionSchema, r as identityRefs, t as BASE_REF } from "./projection-C_EMRmZ8.mjs";
+import { i as projectionSchema, r as identityRefs, t as BASE_REF } from "./projection-SCNrLJMV.mjs";
 import { z } from "zod";
 //#region src/schema-meta.ts
 /**

package/dist/{entity-config-Bfq3OkCU.cjs → entity-config-ZSv3XuW_.cjs}

@@ -1,4 +1,4 @@
-const require_projection = require("./projection-BXBkh7qp.cjs");
+const require_projection = require("./projection-DFgCoyZl.cjs");
 let zod = require("zod");
 //#region src/schema-meta.ts
 /**

package/dist/entity-config.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_entity_config = require("./entity-config-Bfq3OkCU.cjs");
+const require_entity_config = require("./entity-config-ZSv3XuW_.cjs");
 exports.CANONICAL_FIELDS = require_entity_config.CANONICAL_FIELDS;
 exports.CRM_CONCEPTS = require_entity_config.CRM_CONCEPTS;
 exports.CUSTOM_CONCEPT = require_entity_config.CUSTOM_CONCEPT;

package/dist/entity-config.mjs

@@ -1,2 +1,2 @@
-import { a as MATERIALIZING_CONCEPTS, c as entitiesConfigSchema, d as relationshipSchema, f as relationshipsSchema, i as ClivlyConfigError, l as filterSchema, n as CRM_CONCEPTS, o as customObjectDeclarations, p as validateEntitiesConfig, r as CUSTOM_CONCEPT, s as defineClivlyConfig, t as CANONICAL_FIELDS, u as projectionFields } from "./entity-config-DFJ8L9jm.mjs";
+import { a as MATERIALIZING_CONCEPTS, c as entitiesConfigSchema, d as relationshipSchema, f as relationshipsSchema, i as ClivlyConfigError, l as filterSchema, n as CRM_CONCEPTS, o as customObjectDeclarations, p as validateEntitiesConfig, r as CUSTOM_CONCEPT, s as defineClivlyConfig, t as CANONICAL_FIELDS, u as projectionFields } from "./entity-config-Dt_KfgRl.mjs";
 export { CANONICAL_FIELDS, CRM_CONCEPTS, CUSTOM_CONCEPT, ClivlyConfigError, MATERIALIZING_CONCEPTS, customObjectDeclarations, defineClivlyConfig, entitiesConfigSchema, filterSchema, projectionFields, relationshipSchema, relationshipsSchema, validateEntitiesConfig };

package/dist/entity-heuristics.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_entity_config = require("./entity-config-Bfq3OkCU.cjs");
+const require_entity_config = require("./entity-config-ZSv3XuW_.cjs");
 const require_mapping_score = require("./mapping-score.cjs");
 //#region src/entity-heuristics.ts
 const TARGET_CONCEPTS = [

package/dist/entity-heuristics.mjs

@@ -1,4 +1,4 @@
-import { a as MATERIALIZING_CONCEPTS } from "./entity-config-DFJ8L9jm.mjs";
+import { a as MATERIALIZING_CONCEPTS } from "./entity-config-Dt_KfgRl.mjs";
 import { CONCEPT_TIERS, FIELD_TIERS, RELATIONSHIP_TIERS, W, isAmbiguous, isNumericLike, isTextLike, isTimestampLike, tierFor } from "./mapping-score.mjs";
 //#region src/entity-heuristics.ts
 const TARGET_CONCEPTS = [

package/dist/index.cjs

@@ -1,10 +1,10 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_auth_adapter = require("./auth-adapter.cjs");
-const require_projection = require("./projection-BXBkh7qp.cjs");
-const require_entity_config = require("./entity-config-Bfq3OkCU.cjs");
+const require_projection = require("./projection-DFgCoyZl.cjs");
+const require_entity_config = require("./entity-config-ZSv3XuW_.cjs");
 const require_mapping_form = require("./mapping-form.cjs");
 const require_mappings_config = require("./mappings-config.cjs");
-const require_view_compiler = require("./view-compiler-BpNI8Ttw.cjs");
+const require_view_compiler = require("./view-compiler-DTGSwTcz.cjs");
 const require_sync_engine = require("./sync-engine.cjs");
 //#region src/projection-draft.ts
 function emptyProjectionDraft(baseTable) {
@@ -83,6 +83,9 @@ exports.buildRelationships = require_mapping_form.buildRelationships;
 exports.columnMetaFor = require_entity_config.columnMetaFor;
 exports.compileEntityView = require_view_compiler.compileEntityView;
 exports.compileEntityViews = require_view_compiler.compileEntityViews;
+exports.compileProjectionFrom = require_view_compiler.compileProjectionFrom;
+exports.compileProjectionIdentity = require_view_compiler.compileProjectionIdentity;
+exports.compileProjectionJoins = require_view_compiler.compileProjectionJoins;
 exports.coversUniqueKey = require_entity_config.coversUniqueKey;
 exports.defineClivlyConfig = require_entity_config.defineClivlyConfig;
 exports.describeCardinality = describeCardinality;
@@ -99,6 +102,7 @@ exports.joinFansOut = require_entity_config.joinFansOut;
 exports.mappingsToEntitiesConfig = require_mappings_config.mappingsToEntitiesConfig;
 exports.primaryKeyColumns = require_entity_config.primaryKeyColumns;
 exports.projectionSchema = require_projection.projectionSchema;
+exports.quoteIdent = require_view_compiler.quoteIdent;
 exports.reconcile = require_sync_engine.reconcile;
 exports.relationshipSchema = require_entity_config.relationshipSchema;
 exports.relationshipViaSignature = require_mapping_form.relationshipViaSignature;

package/dist/index.d.cts

@@ -2,6 +2,7 @@ import { Activity, ActivityType, Company, Contact, ContactFilters, ContactStatus
 import { CRMAdapter } from "./adapter.cjs";
 import { ClivlyAuthAdapter, ClivlyUser, CrmMembership, MembershipResolver, authCustom } from "./auth-adapter.cjs";
 import { A as BASE_REF, C as defineClivlyConfig, D as relationshipSchema, F as ProjectionRef, I as identityRefs, L as projectionSchema, M as ProjectionIdentity, N as ProjectionJoin, O as relationshipsSchema, P as ProjectionMapping, T as filterSchema, _ as MATERIALIZING_CONCEPTS, a as ClivlyEntitiesConfig, b as RelationshipVia, d as CrmConcept, g as FilterValue, h as FilterExpr, i as ClivlyConfigError, j as ProjectionFieldBinding, k as validateEntitiesConfig, l as ConfigValidationError, m as DiscoveredSchemaTable, n as CRM_CONCEPTS, p as DiscoveredColumnMeta, s as ClivlyEntityConfig, t as CANONICAL_FIELDS, u as ConfigValidationResult, v as MaterializingConcept, w as entitiesConfigSchema, x as RelationshipsMap, y as RelationshipSpec } from "./entity-config-buOIVtMM.cjs";
+import { ConnectionLiveness, IntegrationFacts, IntegrationState, IntegrationStatus, IntegrationStep, NextAction, StepId, StepProblem, StepState } from "./integration-state.cjs";
 import { RelationshipCandidate, buildFilterFromDiscriminator, buildRelationships, relationshipViaSignature } from "./mapping-form.cjs";
 import { EntityMappingRow, mappingsToEntitiesConfig } from "./mappings-config.cjs";
 import { CompileOptions, CompiledView, DEFAULT_VIEW_PREFIX, ExplainResult, compileEntityView, compileEntityViews, explainEntitiesConfig } from "./view-compiler.cjs";
@@ -43,6 +44,34 @@ declare function describeCardinality(draft: ProjectionDraft, schema: DiscoveredS
   joinKey: string;
 }>;
 //#endregion
+//#region src/projection-sql.d.ts
+/**
+ * SQL generation for projection-backed entities.
+ *
+ * Base and joins are aliased by their ref key (`base`, then each join's `key`),
+ * which is what allows the same table to be joined twice and keeps generated
+ * SQL independent of host table names.
+ *
+ * Pure string generation — no DB access. Identifiers are escaped so output is
+ * deterministic and injection-safe.
+ */
+/** Quote a single identifier part, escaping embedded double-quotes. */
+declare function quoteIdent(name: string): string;
+/**
+ * The identity expression. Composite identities concatenate their parts with
+ * `::`; validation guarantees every part is NOT NULL and non-text, which is
+ * what makes the concatenation collision-free.
+ *
+ * Exported unaliased because two paths need the same expression under different
+ * names: the view compiler aliases it `id`, and the SDK's projection push source
+ * also orders and keyset-paginates by it. Sharing one definition is what keeps
+ * a pushed row's `id` identical to the one the view would have produced.
+ */
+declare function compileProjectionIdentity(projection: ProjectionMapping, basePkColumn: string): string;
+declare function compileProjectionJoins(projection: ProjectionMapping): string[];
+/** `FROM <baseTable> AS "base"` — the alias every ref resolves against. */
+declare function compileProjectionFrom(projection: ProjectionMapping): string;
+//#endregion
 //#region src/projection-validate.d.ts
 /**
  * Validate a projection against the discovered schema. Returns every error
@@ -76,4 +105,4 @@ declare function coversUniqueKey(table: DiscoveredSchemaTable, columns: string[]
 /** Is this table's payload rich enough to validate a projection against? */
 declare function hasRichMeta(table: DiscoveredSchemaTable): boolean;
 //#endregion
-export { type Activity, type ActivityType, BASE_REF, CANONICAL_FIELDS, type CRMAdapter, CRM_CONCEPTS, type ClivlyAuthAdapter, ClivlyConfigError, type ClivlyEntitiesConfig, type ClivlyEntityConfig, type ClivlyUser, type Company, type CompileOptions, type CompiledView, type ConfigValidationError, type ConfigValidationResult, type Contact, type ContactFilters, type ContactStatus, type CreateActivityInput, type CreateCompanyInput, type CreateContactInput, type CreateDealInput, type CreateTaskInput, type CrmConcept, type CrmMembership, type CrmRole, DEFAULT_VIEW_PREFIX, type Deal, type DealStage, type DiscoveredColumnMeta, type DiscoveredSchemaTable, type EntityMappingRow, type EntitySyncResult, type ExplainResult, type FilterExpr, type FilterValue, MATERIALIZING_CONCEPTS, type MaterializingConcept, type MembershipResolver, type MirrorRecord, type Note, type PersistAction, type ProjectionDraft, type ProjectionFieldBinding, type ProjectionIdentity, type ProjectionJoin, type ProjectionMapping, type ProjectionRef, type RecordSource, type RelationshipCandidate, type RelationshipSpec, type RelationshipVia, type RelationshipsMap, type SourceRow, type SyncAction, type SyncResult, type SyncStore, type Task, type TaskEntityType, type TaskFilters, type TaskPriority, type TaskStatus, type UpdateContactInput, type UpdateDealInput, type UpdateTaskInput, authCustom, buildFilterFromDiscriminator, buildRelationships, columnMetaFor, compileEntityView, compileEntityViews, coversUniqueKey, defineClivlyConfig, describeCardinality, draftErrors, draftToProjection, emptyProjectionDraft, entitiesConfigSchema, explainEntitiesConfig, fanOutJoins, filterSchema, hasRichMeta, identityRefs, joinFansOut, mappingsToEntitiesConfig, primaryKeyColumns, projectionSchema, reconcile, relationshipSchema, relationshipViaSignature, relationshipsSchema, runSync, suggestJoinConditions, validateEntitiesConfig, validateProjection };
+export { type Activity, type ActivityType, BASE_REF, CANONICAL_FIELDS, type CRMAdapter, CRM_CONCEPTS, type ClivlyAuthAdapter, ClivlyConfigError, type ClivlyEntitiesConfig, type ClivlyEntityConfig, type ClivlyUser, type Company, type CompileOptions, type CompiledView, type ConfigValidationError, type ConfigValidationResult, type ConnectionLiveness, type Contact, type ContactFilters, type ContactStatus, type CreateActivityInput, type CreateCompanyInput, type CreateContactInput, type CreateDealInput, type CreateTaskInput, type CrmConcept, type CrmMembership, type CrmRole, DEFAULT_VIEW_PREFIX, type Deal, type DealStage, type DiscoveredColumnMeta, type DiscoveredSchemaTable, type EntityMappingRow, type EntitySyncResult, type ExplainResult, type FilterExpr, type FilterValue, type IntegrationFacts, type IntegrationState, type IntegrationStatus, type IntegrationStep, MATERIALIZING_CONCEPTS, type MaterializingConcept, type MembershipResolver, type MirrorRecord, type NextAction, type Note, type PersistAction, type ProjectionDraft, type ProjectionFieldBinding, type ProjectionIdentity, type ProjectionJoin, type ProjectionMapping, type ProjectionRef, type RecordSource, type RelationshipCandidate, type RelationshipSpec, type RelationshipVia, type RelationshipsMap, type SourceRow, type StepId, type StepProblem, type StepState, type SyncAction, type SyncResult, type SyncStore, type Task, type TaskEntityType, type TaskFilters, type TaskPriority, type TaskStatus, type UpdateContactInput, type UpdateDealInput, type UpdateTaskInput, authCustom, buildFilterFromDiscriminator, buildRelationships, columnMetaFor, compileEntityView, compileEntityViews, compileProjectionFrom, compileProjectionIdentity, compileProjectionJoins, coversUniqueKey, defineClivlyConfig, describeCardinality, draftErrors, draftToProjection, emptyProjectionDraft, entitiesConfigSchema, explainEntitiesConfig, fanOutJoins, filterSchema, hasRichMeta, identityRefs, joinFansOut, mappingsToEntitiesConfig, primaryKeyColumns, projectionSchema, quoteIdent, reconcile, relationshipSchema, relationshipViaSignature, relationshipsSchema, runSync, suggestJoinConditions, validateEntitiesConfig, validateProjection };

package/dist/index.d.mts

@@ -2,6 +2,7 @@ import { Activity, ActivityType, Company, Contact, ContactFilters, ContactStatus
 import { CRMAdapter } from "./adapter.mjs";
 import { ClivlyAuthAdapter, ClivlyUser, CrmMembership, MembershipResolver, authCustom } from "./auth-adapter.mjs";
 import { A as BASE_REF, C as defineClivlyConfig, D as relationshipSchema, F as ProjectionRef, I as identityRefs, L as projectionSchema, M as ProjectionIdentity, N as ProjectionJoin, O as relationshipsSchema, P as ProjectionMapping, T as filterSchema, _ as MATERIALIZING_CONCEPTS, a as ClivlyEntitiesConfig, b as RelationshipVia, d as CrmConcept, g as FilterValue, h as FilterExpr, i as ClivlyConfigError, j as ProjectionFieldBinding, k as validateEntitiesConfig, l as ConfigValidationError, m as DiscoveredSchemaTable, n as CRM_CONCEPTS, p as DiscoveredColumnMeta, s as ClivlyEntityConfig, t as CANONICAL_FIELDS, u as ConfigValidationResult, v as MaterializingConcept, w as entitiesConfigSchema, x as RelationshipsMap, y as RelationshipSpec } from "./entity-config-buOIVtMM.mjs";
+import { ConnectionLiveness, IntegrationFacts, IntegrationState, IntegrationStatus, IntegrationStep, NextAction, StepId, StepProblem, StepState } from "./integration-state.mjs";
 import { RelationshipCandidate, buildFilterFromDiscriminator, buildRelationships, relationshipViaSignature } from "./mapping-form.mjs";
 import { EntityMappingRow, mappingsToEntitiesConfig } from "./mappings-config.mjs";
 import { CompileOptions, CompiledView, DEFAULT_VIEW_PREFIX, ExplainResult, compileEntityView, compileEntityViews, explainEntitiesConfig } from "./view-compiler.mjs";
@@ -43,6 +44,34 @@ declare function describeCardinality(draft: ProjectionDraft, schema: DiscoveredS
   joinKey: string;
 }>;
 //#endregion
+//#region src/projection-sql.d.ts
+/**
+ * SQL generation for projection-backed entities.
+ *
+ * Base and joins are aliased by their ref key (`base`, then each join's `key`),
+ * which is what allows the same table to be joined twice and keeps generated
+ * SQL independent of host table names.
+ *
+ * Pure string generation — no DB access. Identifiers are escaped so output is
+ * deterministic and injection-safe.
+ */
+/** Quote a single identifier part, escaping embedded double-quotes. */
+declare function quoteIdent(name: string): string;
+/**
+ * The identity expression. Composite identities concatenate their parts with
+ * `::`; validation guarantees every part is NOT NULL and non-text, which is
+ * what makes the concatenation collision-free.
+ *
+ * Exported unaliased because two paths need the same expression under different
+ * names: the view compiler aliases it `id`, and the SDK's projection push source
+ * also orders and keyset-paginates by it. Sharing one definition is what keeps
+ * a pushed row's `id` identical to the one the view would have produced.
+ */
+declare function compileProjectionIdentity(projection: ProjectionMapping, basePkColumn: string): string;
+declare function compileProjectionJoins(projection: ProjectionMapping): string[];
+/** `FROM <baseTable> AS "base"` — the alias every ref resolves against. */
+declare function compileProjectionFrom(projection: ProjectionMapping): string;
+//#endregion
 //#region src/projection-validate.d.ts
 /**
  * Validate a projection against the discovered schema. Returns every error
@@ -76,4 +105,4 @@ declare function coversUniqueKey(table: DiscoveredSchemaTable, columns: string[]
 /** Is this table's payload rich enough to validate a projection against? */
 declare function hasRichMeta(table: DiscoveredSchemaTable): boolean;
 //#endregion
-export { type Activity, type ActivityType, BASE_REF, CANONICAL_FIELDS, type CRMAdapter, CRM_CONCEPTS, type ClivlyAuthAdapter, ClivlyConfigError, type ClivlyEntitiesConfig, type ClivlyEntityConfig, type ClivlyUser, type Company, type CompileOptions, type CompiledView, type ConfigValidationError, type ConfigValidationResult, type Contact, type ContactFilters, type ContactStatus, type CreateActivityInput, type CreateCompanyInput, type CreateContactInput, type CreateDealInput, type CreateTaskInput, type CrmConcept, type CrmMembership, type CrmRole, DEFAULT_VIEW_PREFIX, type Deal, type DealStage, type DiscoveredColumnMeta, type DiscoveredSchemaTable, type EntityMappingRow, type EntitySyncResult, type ExplainResult, type FilterExpr, type FilterValue, MATERIALIZING_CONCEPTS, type MaterializingConcept, type MembershipResolver, type MirrorRecord, type Note, type PersistAction, type ProjectionDraft, type ProjectionFieldBinding, type ProjectionIdentity, type ProjectionJoin, type ProjectionMapping, type ProjectionRef, type RecordSource, type RelationshipCandidate, type RelationshipSpec, type RelationshipVia, type RelationshipsMap, type SourceRow, type SyncAction, type SyncResult, type SyncStore, type Task, type TaskEntityType, type TaskFilters, type TaskPriority, type TaskStatus, type UpdateContactInput, type UpdateDealInput, type UpdateTaskInput, authCustom, buildFilterFromDiscriminator, buildRelationships, columnMetaFor, compileEntityView, compileEntityViews, coversUniqueKey, defineClivlyConfig, describeCardinality, draftErrors, draftToProjection, emptyProjectionDraft, entitiesConfigSchema, explainEntitiesConfig, fanOutJoins, filterSchema, hasRichMeta, identityRefs, joinFansOut, mappingsToEntitiesConfig, primaryKeyColumns, projectionSchema, reconcile, relationshipSchema, relationshipViaSignature, relationshipsSchema, runSync, suggestJoinConditions, validateEntitiesConfig, validateProjection };
+export { type Activity, type ActivityType, BASE_REF, CANONICAL_FIELDS, type CRMAdapter, CRM_CONCEPTS, type ClivlyAuthAdapter, ClivlyConfigError, type ClivlyEntitiesConfig, type ClivlyEntityConfig, type ClivlyUser, type Company, type CompileOptions, type CompiledView, type ConfigValidationError, type ConfigValidationResult, type ConnectionLiveness, type Contact, type ContactFilters, type ContactStatus, type CreateActivityInput, type CreateCompanyInput, type CreateContactInput, type CreateDealInput, type CreateTaskInput, type CrmConcept, type CrmMembership, type CrmRole, DEFAULT_VIEW_PREFIX, type Deal, type DealStage, type DiscoveredColumnMeta, type DiscoveredSchemaTable, type EntityMappingRow, type EntitySyncResult, type ExplainResult, type FilterExpr, type FilterValue, type IntegrationFacts, type IntegrationState, type IntegrationStatus, type IntegrationStep, MATERIALIZING_CONCEPTS, type MaterializingConcept, type MembershipResolver, type MirrorRecord, type NextAction, type Note, type PersistAction, type ProjectionDraft, type ProjectionFieldBinding, type ProjectionIdentity, type ProjectionJoin, type ProjectionMapping, type ProjectionRef, type RecordSource, type RelationshipCandidate, type RelationshipSpec, type RelationshipVia, type RelationshipsMap, type SourceRow, type StepId, type StepProblem, type StepState, type SyncAction, type SyncResult, type SyncStore, type Task, type TaskEntityType, type TaskFilters, type TaskPriority, type TaskStatus, type UpdateContactInput, type UpdateDealInput, type UpdateTaskInput, authCustom, buildFilterFromDiscriminator, buildRelationships, columnMetaFor, compileEntityView, compileEntityViews, compileProjectionFrom, compileProjectionIdentity, compileProjectionJoins, coversUniqueKey, defineClivlyConfig, describeCardinality, draftErrors, draftToProjection, emptyProjectionDraft, entitiesConfigSchema, explainEntitiesConfig, fanOutJoins, filterSchema, hasRichMeta, identityRefs, joinFansOut, mappingsToEntitiesConfig, primaryKeyColumns, projectionSchema, quoteIdent, reconcile, relationshipSchema, relationshipViaSignature, relationshipsSchema, runSync, suggestJoinConditions, validateEntitiesConfig, validateProjection };

package/dist/index.mjs

@@ -1,9 +1,9 @@
 import { authCustom } from "./auth-adapter.mjs";
-import { i as projectionSchema, n as PROJECTION_KEY_PATTERN, r as identityRefs, t as BASE_REF } from "./projection-C_EMRmZ8.mjs";
-import { _ as columnMetaFor, a as MATERIALIZING_CONCEPTS, b as primaryKeyColumns, c as entitiesConfigSchema, d as relationshipSchema, f as relationshipsSchema, g as joinFansOut, h as fanOutJoins, i as ClivlyConfigError, l as filterSchema, m as validateProjection, n as CRM_CONCEPTS, p as validateEntitiesConfig, s as defineClivlyConfig, t as CANONICAL_FIELDS, v as coversUniqueKey, y as hasRichMeta } from "./entity-config-DFJ8L9jm.mjs";
+import { i as projectionSchema, n as PROJECTION_KEY_PATTERN, r as identityRefs, t as BASE_REF } from "./projection-SCNrLJMV.mjs";
+import { _ as columnMetaFor, a as MATERIALIZING_CONCEPTS, b as primaryKeyColumns, c as entitiesConfigSchema, d as relationshipSchema, f as relationshipsSchema, g as joinFansOut, h as fanOutJoins, i as ClivlyConfigError, l as filterSchema, m as validateProjection, n as CRM_CONCEPTS, p as validateEntitiesConfig, s as defineClivlyConfig, t as CANONICAL_FIELDS, v as coversUniqueKey, y as hasRichMeta } from "./entity-config-Dt_KfgRl.mjs";
 import { buildFilterFromDiscriminator, buildRelationships, relationshipViaSignature } from "./mapping-form.mjs";
 import { mappingsToEntitiesConfig } from "./mappings-config.mjs";
-import { i as explainEntitiesConfig, n as compileEntityView, r as compileEntityViews, t as DEFAULT_VIEW_PREFIX } from "./view-compiler-CcqsGxv4.mjs";
+import { c as compileProjectionJoins, i as explainEntitiesConfig, l as quoteIdent, n as compileEntityView, o as compileProjectionFrom, r as compileEntityViews, s as compileProjectionIdentity, t as DEFAULT_VIEW_PREFIX } from "./view-compiler-DjzRXiAJ.mjs";
 import { reconcile, runSync } from "./sync-engine.mjs";
 //#region src/projection-draft.ts
 function emptyProjectionDraft(baseTable) {
@@ -70,4 +70,4 @@ function describeCardinality(draft, schema) {
 	}));
 }
 //#endregion
-export { BASE_REF, CANONICAL_FIELDS, CRM_CONCEPTS, ClivlyConfigError, DEFAULT_VIEW_PREFIX, MATERIALIZING_CONCEPTS, authCustom, buildFilterFromDiscriminator, buildRelationships, columnMetaFor, compileEntityView, compileEntityViews, coversUniqueKey, defineClivlyConfig, describeCardinality, draftErrors, draftToProjection, emptyProjectionDraft, entitiesConfigSchema, explainEntitiesConfig, fanOutJoins, filterSchema, hasRichMeta, identityRefs, joinFansOut, mappingsToEntitiesConfig, primaryKeyColumns, projectionSchema, reconcile, relationshipSchema, relationshipViaSignature, relationshipsSchema, runSync, suggestJoinConditions, validateEntitiesConfig, validateProjection };
+export { BASE_REF, CANONICAL_FIELDS, CRM_CONCEPTS, ClivlyConfigError, DEFAULT_VIEW_PREFIX, MATERIALIZING_CONCEPTS, authCustom, buildFilterFromDiscriminator, buildRelationships, columnMetaFor, compileEntityView, compileEntityViews, compileProjectionFrom, compileProjectionIdentity, compileProjectionJoins, coversUniqueKey, defineClivlyConfig, describeCardinality, draftErrors, draftToProjection, emptyProjectionDraft, entitiesConfigSchema, explainEntitiesConfig, fanOutJoins, filterSchema, hasRichMeta, identityRefs, joinFansOut, mappingsToEntitiesConfig, primaryKeyColumns, projectionSchema, quoteIdent, reconcile, relationshipSchema, relationshipViaSignature, relationshipsSchema, runSync, suggestJoinConditions, validateEntitiesConfig, validateProjection };

package/dist/mappings-config.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_entity_config = require("./entity-config-Bfq3OkCU.cjs");
+const require_entity_config = require("./entity-config-ZSv3XuW_.cjs");
 //#region src/mappings-config.ts
 const RESERVED_FIELD = "id";
 /**

package/dist/mappings-config.mjs

@@ -1,4 +1,4 @@
-import { t as CANONICAL_FIELDS } from "./entity-config-DFJ8L9jm.mjs";
+import { t as CANONICAL_FIELDS } from "./entity-config-Dt_KfgRl.mjs";
 //#region src/mappings-config.ts
 const RESERVED_FIELD = "id";
 /**

package/dist/{projection-BXBkh7qp.cjs → projection-DFgCoyZl.cjs}

@@ -16,8 +16,29 @@ let zod = require("zod");
 */
 /** The reserved ref name for the projection's base table. */
 const BASE_REF = "base";
-/** Entity keys become view names (`crm_src_<entityKey>`), so keep them slugs. */
-const PROJECTION_KEY_PATTERN = /^[a-z][a-z0-9_]*$/;
+/**
+* Entity keys become view names (`crm_src_<entityKey>`), so keep them slugs.
+*
+* Accepts hyphens as well as underscores, matching `OBJECT_TYPE_SLUG_PATTERN`
+* on the server. Those two were widened apart: the server learned hyphens
+* because the SDK's own `slugify` collapses non-alphanumerics to them and
+* `clivly status` reports that form as canonical — but this pattern was missed,
+* so `clivly status` would tell you to key an entity `client-accounts` and then
+* `defineClivlyConfig` would reject the config it had just asked for. Same bug,
+* opposite half of the product.
+*
+* Widening is the safe direction: every key that was valid before still is, so
+* nothing existing is renamed. Safe at all because neither use is ever a bare
+* SQL identifier — the view name is quoted (`view-compiler.ts`, `quoteIdent`),
+* and so is a join's `key` when it is emitted as an alias.
+*/
+const PROJECTION_KEY_PATTERN = /^[a-z][a-z0-9_-]*$/;
+/**
+* Stated in prose because the default for a failed `.regex()` reports only the
+* pattern — the developer is told the config is wrong and handed a regex to
+* decode. Naming the rule is what makes the failure actionable.
+*/
+const PROJECTION_KEY_MESSAGE = "must be lowercase letters, digits, \"-\" or \"_\", starting with a letter";
 const projectionRefSchema = zod.z.strictObject({
 	table: zod.z.string().min(1),
 	column: zod.z.string().min(1)
@@ -29,7 +50,7 @@ const projectionJoinConditionSchema = zod.z.strictObject({
 });
 const projectionJoinSchema = zod.z.strictObject({
 	/** SQL alias and ref target. Unique within the projection. */
-	key: zod.z.string().regex(PROJECTION_KEY_PATTERN),
+	key: zod.z.string().regex(PROJECTION_KEY_PATTERN, { message: `join key ${PROJECTION_KEY_MESSAGE}` }),
 	table: zod.z.string().min(1),
 	type: zod.z.enum(["inner", "left"]),
 	on: zod.z.array(projectionJoinConditionSchema).min(1)
@@ -53,7 +74,7 @@ const projectionIdentitySchema = zod.z.union([
 const projectionSchema = zod.z.strictObject({
 	version: zod.z.literal(1),
 	kind: zod.z.literal("projection"),
-	entityKey: zod.z.string().regex(PROJECTION_KEY_PATTERN),
+	entityKey: zod.z.string().regex(PROJECTION_KEY_PATTERN, { message: `entityKey ${PROJECTION_KEY_MESSAGE}` }),
 	baseTable: zod.z.string().min(1),
 	joins: zod.z.array(projectionJoinSchema),
 	fieldBindings: zod.z.record(zod.z.string(), projectionFieldBindingSchema).refine((b) => Object.keys(b).length > 0, { message: "at least one field must be bound" }),

package/dist/{projection-C_EMRmZ8.mjs → projection-SCNrLJMV.mjs}

@@ -16,8 +16,29 @@ import { z } from "zod";
 */
 /** The reserved ref name for the projection's base table. */
 const BASE_REF = "base";
-/** Entity keys become view names (`crm_src_<entityKey>`), so keep them slugs. */
-const PROJECTION_KEY_PATTERN = /^[a-z][a-z0-9_]*$/;
+/**
+* Entity keys become view names (`crm_src_<entityKey>`), so keep them slugs.
+*
+* Accepts hyphens as well as underscores, matching `OBJECT_TYPE_SLUG_PATTERN`
+* on the server. Those two were widened apart: the server learned hyphens
+* because the SDK's own `slugify` collapses non-alphanumerics to them and
+* `clivly status` reports that form as canonical — but this pattern was missed,
+* so `clivly status` would tell you to key an entity `client-accounts` and then
+* `defineClivlyConfig` would reject the config it had just asked for. Same bug,
+* opposite half of the product.
+*
+* Widening is the safe direction: every key that was valid before still is, so
+* nothing existing is renamed. Safe at all because neither use is ever a bare
+* SQL identifier — the view name is quoted (`view-compiler.ts`, `quoteIdent`),
+* and so is a join's `key` when it is emitted as an alias.
+*/
+const PROJECTION_KEY_PATTERN = /^[a-z][a-z0-9_-]*$/;
+/**
+* Stated in prose because the default for a failed `.regex()` reports only the
+* pattern — the developer is told the config is wrong and handed a regex to
+* decode. Naming the rule is what makes the failure actionable.
+*/
+const PROJECTION_KEY_MESSAGE = "must be lowercase letters, digits, \"-\" or \"_\", starting with a letter";
 const projectionRefSchema = z.strictObject({
 	table: z.string().min(1),
 	column: z.string().min(1)
@@ -29,7 +50,7 @@ const projectionJoinConditionSchema = z.strictObject({
 });
 const projectionJoinSchema = z.strictObject({
 	/** SQL alias and ref target. Unique within the projection. */
-	key: z.string().regex(PROJECTION_KEY_PATTERN),
+	key: z.string().regex(PROJECTION_KEY_PATTERN, { message: `join key ${PROJECTION_KEY_MESSAGE}` }),
 	table: z.string().min(1),
 	type: z.enum(["inner", "left"]),
 	on: z.array(projectionJoinConditionSchema).min(1)
@@ -53,7 +74,7 @@ const projectionIdentitySchema = z.union([
 const projectionSchema = z.strictObject({
 	version: z.literal(1),
 	kind: z.literal("projection"),
-	entityKey: z.string().regex(PROJECTION_KEY_PATTERN),
+	entityKey: z.string().regex(PROJECTION_KEY_PATTERN, { message: `entityKey ${PROJECTION_KEY_MESSAGE}` }),
 	baseTable: z.string().min(1),
 	joins: z.array(projectionJoinSchema),
 	fieldBindings: z.record(z.string(), projectionFieldBindingSchema).refine((b) => Object.keys(b).length > 0, { message: "at least one field must be bound" }),

package/dist/sync-engine.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_view_compiler = require("./view-compiler-BpNI8Ttw.cjs");
+const require_view_compiler = require("./view-compiler-DTGSwTcz.cjs");
 //#region src/sync-engine.ts
 /**
 * Diff a view's rows against the current mirror population for one entity.

package/dist/sync-engine.mjs

@@ -1,4 +1,4 @@
-import { r as compileEntityViews } from "./view-compiler-CcqsGxv4.mjs";
+import { r as compileEntityViews } from "./view-compiler-DjzRXiAJ.mjs";
 //#region src/sync-engine.ts
 /**
 * Diff a view's rows against the current mirror population for one entity.

package/dist/{view-compiler-BpNI8Ttw.cjs → view-compiler-DTGSwTcz.cjs}

@@ -1,4 +1,4 @@
-const require_projection = require("./projection-BXBkh7qp.cjs");
+const require_projection = require("./projection-DFgCoyZl.cjs");
 //#region src/projection-sql.ts
 /**
 * SQL generation for projection-backed entities.
@@ -18,16 +18,25 @@ function refSql(ref) {
 	return `${quoteIdent(ref.table)}.${quoteIdent(ref.column)}`;
 }
 /**
-* The identity expression, aliased as `id`. Composite identities concatenate
-* their parts with `::`; validation guarantees every part is NOT NULL and
-* non-text, which is what makes the concatenation collision-free.
+* The identity expression. Composite identities concatenate their parts with
+* `::`; validation guarantees every part is NOT NULL and non-text, which is
+* what makes the concatenation collision-free.
+*
+* Exported unaliased because two paths need the same expression under different
+* names: the view compiler aliases it `id`, and the SDK's projection push source
+* also orders and keyset-paginates by it. Sharing one definition is what keeps
+* a pushed row's `id` identical to the one the view would have produced.
 */
-function identitySql(projection, basePkColumn) {
+function compileProjectionIdentity(projection, basePkColumn) {
 	const refs = require_projection.identityRefs(projection.identity, basePkColumn);
-	if (projection.identity.kind === "composite") return `CONCAT_WS('::', ${refs.map((ref) => `${refSql(ref)}::text`).join(", ")}) AS ${quoteIdent("id")}`;
+	if (projection.identity.kind === "composite") return `CONCAT_WS('::', ${refs.map((ref) => `${refSql(ref)}::text`).join(", ")})`;
 	const [ref] = refs;
 	if (!ref) throw new Error("projection identity resolved to no column");
-	return `${refSql(ref)} AS ${quoteIdent("id")}`;
+	return refSql(ref);
+}
+/** The identity expression, aliased as `id`. */
+function identitySql(projection, basePkColumn) {
+	return `${compileProjectionIdentity(projection, basePkColumn)} AS ${quoteIdent("id")}`;
 }
 function compileProjectionSelect(projection, basePkColumn) {
 	const selectItems = [identitySql(projection, basePkColumn)];
@@ -285,6 +294,24 @@ Object.defineProperty(exports, "compileEntityViews", {
 		return compileEntityViews;
 	}
 });
+Object.defineProperty(exports, "compileProjectionFrom", {
+	enumerable: true,
+	get: function() {
+		return compileProjectionFrom;
+	}
+});
+Object.defineProperty(exports, "compileProjectionIdentity", {
+	enumerable: true,
+	get: function() {
+		return compileProjectionIdentity;
+	}
+});
+Object.defineProperty(exports, "compileProjectionJoins", {
+	enumerable: true,
+	get: function() {
+		return compileProjectionJoins;
+	}
+});
 Object.defineProperty(exports, "explainEntitiesConfig", {
 	enumerable: true,
 	get: function() {
@@ -297,3 +324,9 @@ Object.defineProperty(exports, "explainViewExecutionError", {
 		return explainViewExecutionError;
 	}
 });
+Object.defineProperty(exports, "quoteIdent", {
+	enumerable: true,
+	get: function() {
+		return quoteIdent;
+	}
+});

package/dist/{view-compiler-CcqsGxv4.mjs → view-compiler-DjzRXiAJ.mjs}

@@ -1,4 +1,4 @@
-import { r as identityRefs, t as BASE_REF } from "./projection-C_EMRmZ8.mjs";
+import { r as identityRefs, t as BASE_REF } from "./projection-SCNrLJMV.mjs";
 //#region src/projection-sql.ts
 /**
 * SQL generation for projection-backed entities.
@@ -18,16 +18,25 @@ function refSql(ref) {
 	return `${quoteIdent(ref.table)}.${quoteIdent(ref.column)}`;
 }
 /**
-* The identity expression, aliased as `id`. Composite identities concatenate
-* their parts with `::`; validation guarantees every part is NOT NULL and
-* non-text, which is what makes the concatenation collision-free.
+* The identity expression. Composite identities concatenate their parts with
+* `::`; validation guarantees every part is NOT NULL and non-text, which is
+* what makes the concatenation collision-free.
+*
+* Exported unaliased because two paths need the same expression under different
+* names: the view compiler aliases it `id`, and the SDK's projection push source
+* also orders and keyset-paginates by it. Sharing one definition is what keeps
+* a pushed row's `id` identical to the one the view would have produced.
 */
-function identitySql(projection, basePkColumn) {
+function compileProjectionIdentity(projection, basePkColumn) {
 	const refs = identityRefs(projection.identity, basePkColumn);
-	if (projection.identity.kind === "composite") return `CONCAT_WS('::', ${refs.map((ref) => `${refSql(ref)}::text`).join(", ")}) AS ${quoteIdent("id")}`;
+	if (projection.identity.kind === "composite") return `CONCAT_WS('::', ${refs.map((ref) => `${refSql(ref)}::text`).join(", ")})`;
 	const [ref] = refs;
 	if (!ref) throw new Error("projection identity resolved to no column");
-	return `${refSql(ref)} AS ${quoteIdent("id")}`;
+	return refSql(ref);
+}
+/** The identity expression, aliased as `id`. */
+function identitySql(projection, basePkColumn) {
+	return `${compileProjectionIdentity(projection, basePkColumn)} AS ${quoteIdent("id")}`;
 }
 function compileProjectionSelect(projection, basePkColumn) {
 	const selectItems = [identitySql(projection, basePkColumn)];
@@ -267,4 +276,4 @@ async function explainEntitiesConfig(config, run, options = {}) {
 	return results;
 }
 //#endregion
-export { explainViewExecutionError as a, explainEntitiesConfig as i, compileEntityView as n, compileEntityViews as r, DEFAULT_VIEW_PREFIX as t };
+export { explainViewExecutionError as a, compileProjectionJoins as c, explainEntitiesConfig as i, quoteIdent as l, compileEntityView as n, compileProjectionFrom as o, compileEntityViews as r, compileProjectionIdentity as s, DEFAULT_VIEW_PREFIX as t };

package/dist/view-compiler.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_view_compiler = require("./view-compiler-BpNI8Ttw.cjs");
+const require_view_compiler = require("./view-compiler-DTGSwTcz.cjs");
 exports.DEFAULT_VIEW_PREFIX = require_view_compiler.DEFAULT_VIEW_PREFIX;
 exports.compileEntityView = require_view_compiler.compileEntityView;
 exports.compileEntityViews = require_view_compiler.compileEntityViews;

package/dist/view-compiler.mjs

@@ -1,2 +1,2 @@
-import { a as explainViewExecutionError, i as explainEntitiesConfig, n as compileEntityView, r as compileEntityViews, t as DEFAULT_VIEW_PREFIX } from "./view-compiler-CcqsGxv4.mjs";
+import { a as explainViewExecutionError, i as explainEntitiesConfig, n as compileEntityView, r as compileEntityViews, t as DEFAULT_VIEW_PREFIX } from "./view-compiler-DjzRXiAJ.mjs";
 export { DEFAULT_VIEW_PREFIX, compileEntityView, compileEntityViews, explainEntitiesConfig, explainViewExecutionError };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clivly/core",
-  "version": "0.9.2",
+  "version": "0.9.4",
   "private": false,
   "type": "module",
   "description": "ORM/auth-agnostic CRM adapter contracts and shared domain types for Clivly.",