@clivly/core 0.9.0 → 0.9.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (38) hide show
  1. package/README.md +88 -3
  2. package/dist/drizzle.d.cts +1 -1
  3. package/dist/drizzle.d.mts +1 -1
  4. package/dist/{entity-config-Tb5bbKLj.mjs → entity-config-8Fgr6IOH.mjs} +47 -2
  5. package/dist/entity-config-CLxI8dVb.d.cts +556 -0
  6. package/dist/entity-config-CLxI8dVb.d.mts +556 -0
  7. package/dist/{entity-config-PoOGzvpN.cjs → entity-config-Dh8aEcgj.cjs} +52 -1
  8. package/dist/entity-config.cjs +2 -1
  9. package/dist/entity-config.d.cts +2 -414
  10. package/dist/entity-config.d.mts +2 -414
  11. package/dist/entity-config.mjs +2 -2
  12. package/dist/entity-heuristics.cjs +1 -1
  13. package/dist/entity-heuristics.d.cts +1 -1
  14. package/dist/entity-heuristics.d.mts +1 -1
  15. package/dist/entity-heuristics.mjs +1 -1
  16. package/dist/index.cjs +2 -2
  17. package/dist/index.d.cts +2 -2
  18. package/dist/index.d.mts +2 -2
  19. package/dist/index.mjs +2 -2
  20. package/dist/mapping-form.d.cts +1 -1
  21. package/dist/mapping-form.d.mts +1 -1
  22. package/dist/mappings-config.cjs +1 -1
  23. package/dist/mappings-config.d.cts +46 -1
  24. package/dist/mappings-config.d.mts +46 -1
  25. package/dist/mappings-config.mjs +1 -1
  26. package/dist/sync-engine.cjs +1 -1
  27. package/dist/sync-engine.d.cts +1 -1
  28. package/dist/sync-engine.d.mts +1 -1
  29. package/dist/sync-engine.mjs +1 -1
  30. package/dist/{view-compiler-BwZ9UgLp.cjs → view-compiler-BpNI8Ttw.cjs} +22 -0
  31. package/dist/{view-compiler-BKrBA_II.mjs → view-compiler-CcqsGxv4.mjs} +17 -1
  32. package/dist/view-compiler.cjs +2 -1
  33. package/dist/view-compiler.d.cts +12 -2
  34. package/dist/view-compiler.d.mts +12 -2
  35. package/dist/view-compiler.mjs +2 -2
  36. package/package.json +1 -1
  37. package/dist/mappings-config-B0W5bVZj.d.mts +0 -168
  38. package/dist/mappings-config-BWo4cRDF.d.cts +0 -168
@@ -1,4 +1,4 @@
1
- import { ClivlyEntitiesConfig } from "./entity-config.cjs";
1
+ import { a as ClivlyEntitiesConfig } from "./entity-config-CLxI8dVb.cjs";
2
2
  import { CompileOptions, CompiledView } from "./view-compiler.cjs";
3
3
  //#region src/sync-engine.d.ts
4
4
  /**
@@ -1,4 +1,4 @@
1
- import { ClivlyEntitiesConfig } from "./entity-config.mjs";
1
+ import { a as ClivlyEntitiesConfig } from "./entity-config-CLxI8dVb.mjs";
2
2
  import { CompileOptions, CompiledView } from "./view-compiler.mjs";
3
3
  //#region src/sync-engine.d.ts
4
4
  /**
@@ -1,4 +1,4 @@
1
- import { r as compileEntityViews } from "./view-compiler-BKrBA_II.mjs";
1
+ import { r as compileEntityViews } from "./view-compiler-CcqsGxv4.mjs";
2
2
  //#region src/sync-engine.ts
3
3
  /**
4
4
  * Diff a view's rows against the current mirror population for one entity.
@@ -186,6 +186,22 @@ function legacyJoins(config, entity, columns, selectItems) {
186
186
  }
187
187
  return joins;
188
188
  }
189
+ /**
190
+ * Translate a driver error from executing a compiled view into something
191
+ * actionable, or `undefined` when it is not one we recognise (caller rethrows).
192
+ *
193
+ * The case that matters: `WITH (security_invoker = true)` needs Postgres 15,
194
+ * and PG 14 rejects it with sqlstate 22023 naming a Postgres internal
195
+ * (`reloptions.c`) — no mention of Clivly, the option, or the version. The
196
+ * compiler cannot catch this itself because the host executes the SQL.
197
+ */
198
+ function explainViewExecutionError(error) {
199
+ if (typeof error !== "object" || error === null) return;
200
+ const { code, routine } = error;
201
+ const message = error instanceof Error ? error.message : "";
202
+ if (!(code === "22023" && (routine === "parseRelOptionsInternal" || message.includes("security_invoker")))) return;
203
+ return "CREATE VIEW … WITH (security_invoker = true) requires Postgres 15+. Pass `securityInvoker: false` to compile without it — but note the view then runs with its owner's privileges instead of the querying role's, which bypasses row-level security (RLS) on the underlying tables. Prefer upgrading Postgres if you rely on RLS to separate tenants.";
204
+ }
189
205
  function compileEntityView(config, entityKey, options = {}) {
190
206
  const entity = config.entities[entityKey];
191
207
  if (!entity) throw new Error(`entity "${entityKey}" is not defined`);
@@ -275,3 +291,9 @@ Object.defineProperty(exports, "explainEntitiesConfig", {
275
291
  return explainEntitiesConfig;
276
292
  }
277
293
  });
294
+ Object.defineProperty(exports, "explainViewExecutionError", {
295
+ enumerable: true,
296
+ get: function() {
297
+ return explainViewExecutionError;
298
+ }
299
+ });
@@ -186,6 +186,22 @@ function legacyJoins(config, entity, columns, selectItems) {
186
186
  }
187
187
  return joins;
188
188
  }
189
+ /**
190
+ * Translate a driver error from executing a compiled view into something
191
+ * actionable, or `undefined` when it is not one we recognise (caller rethrows).
192
+ *
193
+ * The case that matters: `WITH (security_invoker = true)` needs Postgres 15,
194
+ * and PG 14 rejects it with sqlstate 22023 naming a Postgres internal
195
+ * (`reloptions.c`) — no mention of Clivly, the option, or the version. The
196
+ * compiler cannot catch this itself because the host executes the SQL.
197
+ */
198
+ function explainViewExecutionError(error) {
199
+ if (typeof error !== "object" || error === null) return;
200
+ const { code, routine } = error;
201
+ const message = error instanceof Error ? error.message : "";
202
+ if (!(code === "22023" && (routine === "parseRelOptionsInternal" || message.includes("security_invoker")))) return;
203
+ return "CREATE VIEW … WITH (security_invoker = true) requires Postgres 15+. Pass `securityInvoker: false` to compile without it — but note the view then runs with its owner's privileges instead of the querying role's, which bypasses row-level security (RLS) on the underlying tables. Prefer upgrading Postgres if you rely on RLS to separate tenants.";
204
+ }
189
205
  function compileEntityView(config, entityKey, options = {}) {
190
206
  const entity = config.entities[entityKey];
191
207
  if (!entity) throw new Error(`entity "${entityKey}" is not defined`);
@@ -251,4 +267,4 @@ async function explainEntitiesConfig(config, run, options = {}) {
251
267
  return results;
252
268
  }
253
269
  //#endregion
254
- export { explainEntitiesConfig as i, compileEntityView as n, compileEntityViews as r, DEFAULT_VIEW_PREFIX as t };
270
+ export { explainViewExecutionError as a, explainEntitiesConfig as i, compileEntityView as n, compileEntityViews as r, DEFAULT_VIEW_PREFIX as t };
@@ -1,6 +1,7 @@
1
1
  Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
2
- const require_view_compiler = require("./view-compiler-BwZ9UgLp.cjs");
2
+ const require_view_compiler = require("./view-compiler-BpNI8Ttw.cjs");
3
3
  exports.DEFAULT_VIEW_PREFIX = require_view_compiler.DEFAULT_VIEW_PREFIX;
4
4
  exports.compileEntityView = require_view_compiler.compileEntityView;
5
5
  exports.compileEntityViews = require_view_compiler.compileEntityViews;
6
6
  exports.explainEntitiesConfig = require_view_compiler.explainEntitiesConfig;
7
+ exports.explainViewExecutionError = require_view_compiler.explainViewExecutionError;
@@ -1,4 +1,4 @@
1
- import { ClivlyEntitiesConfig } from "./entity-config.cjs";
1
+ import { a as ClivlyEntitiesConfig } from "./entity-config-CLxI8dVb.cjs";
2
2
  //#region src/view-compiler.d.ts
3
3
  declare const DEFAULT_VIEW_PREFIX = "crm_src_";
4
4
  interface CompileOptions {
@@ -43,6 +43,16 @@ interface CompiledView {
43
43
  sql: string;
44
44
  viewName: string;
45
45
  }
46
+ /**
47
+ * Translate a driver error from executing a compiled view into something
48
+ * actionable, or `undefined` when it is not one we recognise (caller rethrows).
49
+ *
50
+ * The case that matters: `WITH (security_invoker = true)` needs Postgres 15,
51
+ * and PG 14 rejects it with sqlstate 22023 naming a Postgres internal
52
+ * (`reloptions.c`) — no mention of Clivly, the option, or the version. The
53
+ * compiler cannot catch this itself because the host executes the SQL.
54
+ */
55
+ declare function explainViewExecutionError(error: unknown): string | undefined;
46
56
  declare function compileEntityView(config: ClivlyEntitiesConfig, entityKey: string, options?: CompileOptions): CompiledView;
47
57
  /** Compile every entity in the config into its view, in declaration order. */
48
58
  declare function compileEntityViews(config: ClivlyEntitiesConfig, options?: CompileOptions): CompiledView[];
@@ -68,4 +78,4 @@ interface ExplainResult {
68
78
  */
69
79
  declare function explainEntitiesConfig(config: ClivlyEntitiesConfig, run: (sql: string) => Promise<unknown>, options?: CompileOptions): Promise<ExplainResult[]>;
70
80
  //#endregion
71
- export { CompileOptions, CompiledView, DEFAULT_VIEW_PREFIX, ExplainResult, compileEntityView, compileEntityViews, explainEntitiesConfig };
81
+ export { CompileOptions, CompiledView, DEFAULT_VIEW_PREFIX, ExplainResult, compileEntityView, compileEntityViews, explainEntitiesConfig, explainViewExecutionError };
@@ -1,4 +1,4 @@
1
- import { ClivlyEntitiesConfig } from "./entity-config.mjs";
1
+ import { a as ClivlyEntitiesConfig } from "./entity-config-CLxI8dVb.mjs";
2
2
  //#region src/view-compiler.d.ts
3
3
  declare const DEFAULT_VIEW_PREFIX = "crm_src_";
4
4
  interface CompileOptions {
@@ -43,6 +43,16 @@ interface CompiledView {
43
43
  sql: string;
44
44
  viewName: string;
45
45
  }
46
+ /**
47
+ * Translate a driver error from executing a compiled view into something
48
+ * actionable, or `undefined` when it is not one we recognise (caller rethrows).
49
+ *
50
+ * The case that matters: `WITH (security_invoker = true)` needs Postgres 15,
51
+ * and PG 14 rejects it with sqlstate 22023 naming a Postgres internal
52
+ * (`reloptions.c`) — no mention of Clivly, the option, or the version. The
53
+ * compiler cannot catch this itself because the host executes the SQL.
54
+ */
55
+ declare function explainViewExecutionError(error: unknown): string | undefined;
46
56
  declare function compileEntityView(config: ClivlyEntitiesConfig, entityKey: string, options?: CompileOptions): CompiledView;
47
57
  /** Compile every entity in the config into its view, in declaration order. */
48
58
  declare function compileEntityViews(config: ClivlyEntitiesConfig, options?: CompileOptions): CompiledView[];
@@ -68,4 +78,4 @@ interface ExplainResult {
68
78
  */
69
79
  declare function explainEntitiesConfig(config: ClivlyEntitiesConfig, run: (sql: string) => Promise<unknown>, options?: CompileOptions): Promise<ExplainResult[]>;
70
80
  //#endregion
71
- export { CompileOptions, CompiledView, DEFAULT_VIEW_PREFIX, ExplainResult, compileEntityView, compileEntityViews, explainEntitiesConfig };
81
+ export { CompileOptions, CompiledView, DEFAULT_VIEW_PREFIX, ExplainResult, compileEntityView, compileEntityViews, explainEntitiesConfig, explainViewExecutionError };
@@ -1,2 +1,2 @@
1
- import { i as explainEntitiesConfig, n as compileEntityView, r as compileEntityViews, t as DEFAULT_VIEW_PREFIX } from "./view-compiler-BKrBA_II.mjs";
2
- export { DEFAULT_VIEW_PREFIX, compileEntityView, compileEntityViews, explainEntitiesConfig };
1
+ import { a as explainViewExecutionError, i as explainEntitiesConfig, n as compileEntityView, r as compileEntityViews, t as DEFAULT_VIEW_PREFIX } from "./view-compiler-CcqsGxv4.mjs";
2
+ export { DEFAULT_VIEW_PREFIX, compileEntityView, compileEntityViews, explainEntitiesConfig, explainViewExecutionError };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@clivly/core",
3
- "version": "0.9.0",
3
+ "version": "0.9.1",
4
4
  "private": false,
5
5
  "type": "module",
6
6
  "description": "ORM/auth-agnostic CRM adapter contracts and shared domain types for Clivly.",
@@ -1,168 +0,0 @@
1
- import { ClivlyEntitiesConfig } from "./entity-config.mjs";
2
- import { z } from "zod";
3
- //#region src/projection.d.ts
4
- /**
5
- * Projection-backed custom mappings — one custom object derived from a base
6
- * table plus explicit joins.
7
- *
8
- * A projection is deliberately narrow: equality joins only, direct column
9
- * bindings only, no expressions and no aggregation. Everything a user can
10
- * express here compiles to a single read-only view whose `id` column is
11
- * provably unique per row, which is what lets the sync engine consume it
12
- * unchanged.
13
- *
14
- * Refs address tables symbolically: `"base"` for the base table, or a join's
15
- * `key`. Raw table names are never accepted in a ref, so a projection can
16
- * never reach a table it did not declare.
17
- */
18
- /** The reserved ref name for the projection's base table. */
19
- declare const BASE_REF = "base";
20
- declare const projectionRefSchema: z.ZodObject<{
21
- table: z.ZodString;
22
- column: z.ZodString;
23
- }, z.core.$strict>;
24
- type ProjectionRef = z.infer<typeof projectionRefSchema>;
25
- declare const projectionJoinSchema: z.ZodObject<{
26
- key: z.ZodString;
27
- table: z.ZodString;
28
- type: z.ZodEnum<{
29
- inner: "inner";
30
- left: "left";
31
- }>;
32
- on: z.ZodArray<z.ZodObject<{
33
- left: z.ZodObject<{
34
- table: z.ZodString;
35
- column: z.ZodString;
36
- }, z.core.$strict>;
37
- op: z.ZodLiteral<"eq">;
38
- right: z.ZodObject<{
39
- table: z.ZodString;
40
- column: z.ZodString;
41
- }, z.core.$strict>;
42
- }, z.core.$strict>>;
43
- }, z.core.$strict>;
44
- type ProjectionJoin = z.infer<typeof projectionJoinSchema>;
45
- declare const projectionFieldBindingSchema: z.ZodObject<{
46
- from: z.ZodObject<{
47
- table: z.ZodString;
48
- column: z.ZodString;
49
- }, z.core.$strict>;
50
- }, z.core.$strict>;
51
- type ProjectionFieldBinding = z.infer<typeof projectionFieldBindingSchema>;
52
- declare const projectionIdentitySchema: z.ZodUnion<readonly [z.ZodObject<{
53
- kind: z.ZodLiteral<"base_pk">;
54
- column: z.ZodOptional<z.ZodString>;
55
- }, z.core.$strict>, z.ZodObject<{
56
- kind: z.ZodLiteral<"column">;
57
- from: z.ZodObject<{
58
- table: z.ZodString;
59
- column: z.ZodString;
60
- }, z.core.$strict>;
61
- }, z.core.$strict>, z.ZodObject<{
62
- kind: z.ZodLiteral<"composite">;
63
- parts: z.ZodArray<z.ZodObject<{
64
- table: z.ZodString;
65
- column: z.ZodString;
66
- }, z.core.$strict>>;
67
- }, z.core.$strict>]>;
68
- type ProjectionIdentity = z.infer<typeof projectionIdentitySchema>;
69
- declare const projectionSchema: z.ZodObject<{
70
- version: z.ZodLiteral<1>;
71
- kind: z.ZodLiteral<"projection">;
72
- entityKey: z.ZodString;
73
- baseTable: z.ZodString;
74
- joins: z.ZodArray<z.ZodObject<{
75
- key: z.ZodString;
76
- table: z.ZodString;
77
- type: z.ZodEnum<{
78
- inner: "inner";
79
- left: "left";
80
- }>;
81
- on: z.ZodArray<z.ZodObject<{
82
- left: z.ZodObject<{
83
- table: z.ZodString;
84
- column: z.ZodString;
85
- }, z.core.$strict>;
86
- op: z.ZodLiteral<"eq">;
87
- right: z.ZodObject<{
88
- table: z.ZodString;
89
- column: z.ZodString;
90
- }, z.core.$strict>;
91
- }, z.core.$strict>>;
92
- }, z.core.$strict>>;
93
- fieldBindings: z.ZodRecord<z.ZodString, z.ZodObject<{
94
- from: z.ZodObject<{
95
- table: z.ZodString;
96
- column: z.ZodString;
97
- }, z.core.$strict>;
98
- }, z.core.$strict>>;
99
- identity: z.ZodUnion<readonly [z.ZodObject<{
100
- kind: z.ZodLiteral<"base_pk">;
101
- column: z.ZodOptional<z.ZodString>;
102
- }, z.core.$strict>, z.ZodObject<{
103
- kind: z.ZodLiteral<"column">;
104
- from: z.ZodObject<{
105
- table: z.ZodString;
106
- column: z.ZodString;
107
- }, z.core.$strict>;
108
- }, z.core.$strict>, z.ZodObject<{
109
- kind: z.ZodLiteral<"composite">;
110
- parts: z.ZodArray<z.ZodObject<{
111
- table: z.ZodString;
112
- column: z.ZodString;
113
- }, z.core.$strict>>;
114
- }, z.core.$strict>]>;
115
- }, z.core.$strict>;
116
- type ProjectionMapping = z.infer<typeof projectionSchema>;
117
- /**
118
- * Every column ref an identity depends on. `basePkColumn` is the base table's
119
- * discovered PK, used only when a `base_pk` identity omits an explicit column.
120
- */
121
- declare function identityRefs(identity: ProjectionIdentity, basePkColumn: string): ProjectionRef[];
122
- //#endregion
123
- //#region src/mappings-config.d.ts
124
- /**
125
- * Mappings → Entity Config bridge.
126
- *
127
- * `crm_entity_mappings` rows are the single source of truth for how a host
128
- * schema maps onto Clivly's CRM concepts. This module compiles those rows into
129
- * a `ClivlyEntitiesConfig` — the contract the view compiler and sync engine
130
- * consume — so the persisted mapping and the runtime pipeline never diverge.
131
- *
132
- * The row model has no explicit entity-key column (it's keyed by
133
- * `sourceTable + targetConcept + role`), but the config's `relationships`
134
- * reference other entities *by key*. This builder therefore derives a stable
135
- * key per row and resolves each relationship's `entity` reference through the
136
- * same derivation — so a relationship stored as `entity: "<relatedTable>"`
137
- * (the shape `mappings.suggest` produces) resolves to the right entity.
138
- */
139
- /**
140
- * A persisted `crm_entity_mappings` row, narrowed to the columns the builder
141
- * reads. Structurally compatible with the Drizzle row (jsonb columns typed
142
- * loosely) so the API layer can pass `db.select()` results straight in.
143
- */
144
- interface EntityMappingRow {
145
- fieldMap: Record<string, string>;
146
- filter?: Record<string, unknown> | null;
147
- /**
148
- * Advanced mapping: a base table plus explicit joins. When set, this — not
149
- * `fieldMap` — is the authored source of truth, and `sourceTable` merely
150
- * mirrors `projection.baseTable`.
151
- */
152
- projection?: ProjectionMapping | null;
153
- relationships?: Record<string, unknown> | null;
154
- role?: string | null;
155
- sourceTable: string;
156
- status?: string | null;
157
- targetConcept: string;
158
- targetObjectTypeId?: string | null;
159
- }
160
- /**
161
- * Compile persisted mapping rows into a `ClivlyEntitiesConfig`. Only `active`
162
- * rows with at least one mapped field are included; disabled/suggested rows and
163
- * unmapped rows are skipped. Returns `{ entities: {} }` when nothing is
164
- * eligible — a no-op the view compiler and sync engine both tolerate.
165
- */
166
- declare function mappingsToEntitiesConfig(rows: EntityMappingRow[]): ClivlyEntitiesConfig;
167
- //#endregion
168
- export { ProjectionIdentity as a, ProjectionRef as c, ProjectionFieldBinding as i, identityRefs as l, mappingsToEntitiesConfig as n, ProjectionJoin as o, BASE_REF as r, ProjectionMapping as s, EntityMappingRow as t, projectionSchema as u };
@@ -1,168 +0,0 @@
1
- import { ClivlyEntitiesConfig } from "./entity-config.cjs";
2
- import { z } from "zod";
3
- //#region src/projection.d.ts
4
- /**
5
- * Projection-backed custom mappings — one custom object derived from a base
6
- * table plus explicit joins.
7
- *
8
- * A projection is deliberately narrow: equality joins only, direct column
9
- * bindings only, no expressions and no aggregation. Everything a user can
10
- * express here compiles to a single read-only view whose `id` column is
11
- * provably unique per row, which is what lets the sync engine consume it
12
- * unchanged.
13
- *
14
- * Refs address tables symbolically: `"base"` for the base table, or a join's
15
- * `key`. Raw table names are never accepted in a ref, so a projection can
16
- * never reach a table it did not declare.
17
- */
18
- /** The reserved ref name for the projection's base table. */
19
- declare const BASE_REF = "base";
20
- declare const projectionRefSchema: z.ZodObject<{
21
- table: z.ZodString;
22
- column: z.ZodString;
23
- }, z.core.$strict>;
24
- type ProjectionRef = z.infer<typeof projectionRefSchema>;
25
- declare const projectionJoinSchema: z.ZodObject<{
26
- key: z.ZodString;
27
- table: z.ZodString;
28
- type: z.ZodEnum<{
29
- inner: "inner";
30
- left: "left";
31
- }>;
32
- on: z.ZodArray<z.ZodObject<{
33
- left: z.ZodObject<{
34
- table: z.ZodString;
35
- column: z.ZodString;
36
- }, z.core.$strict>;
37
- op: z.ZodLiteral<"eq">;
38
- right: z.ZodObject<{
39
- table: z.ZodString;
40
- column: z.ZodString;
41
- }, z.core.$strict>;
42
- }, z.core.$strict>>;
43
- }, z.core.$strict>;
44
- type ProjectionJoin = z.infer<typeof projectionJoinSchema>;
45
- declare const projectionFieldBindingSchema: z.ZodObject<{
46
- from: z.ZodObject<{
47
- table: z.ZodString;
48
- column: z.ZodString;
49
- }, z.core.$strict>;
50
- }, z.core.$strict>;
51
- type ProjectionFieldBinding = z.infer<typeof projectionFieldBindingSchema>;
52
- declare const projectionIdentitySchema: z.ZodUnion<readonly [z.ZodObject<{
53
- kind: z.ZodLiteral<"base_pk">;
54
- column: z.ZodOptional<z.ZodString>;
55
- }, z.core.$strict>, z.ZodObject<{
56
- kind: z.ZodLiteral<"column">;
57
- from: z.ZodObject<{
58
- table: z.ZodString;
59
- column: z.ZodString;
60
- }, z.core.$strict>;
61
- }, z.core.$strict>, z.ZodObject<{
62
- kind: z.ZodLiteral<"composite">;
63
- parts: z.ZodArray<z.ZodObject<{
64
- table: z.ZodString;
65
- column: z.ZodString;
66
- }, z.core.$strict>>;
67
- }, z.core.$strict>]>;
68
- type ProjectionIdentity = z.infer<typeof projectionIdentitySchema>;
69
- declare const projectionSchema: z.ZodObject<{
70
- version: z.ZodLiteral<1>;
71
- kind: z.ZodLiteral<"projection">;
72
- entityKey: z.ZodString;
73
- baseTable: z.ZodString;
74
- joins: z.ZodArray<z.ZodObject<{
75
- key: z.ZodString;
76
- table: z.ZodString;
77
- type: z.ZodEnum<{
78
- inner: "inner";
79
- left: "left";
80
- }>;
81
- on: z.ZodArray<z.ZodObject<{
82
- left: z.ZodObject<{
83
- table: z.ZodString;
84
- column: z.ZodString;
85
- }, z.core.$strict>;
86
- op: z.ZodLiteral<"eq">;
87
- right: z.ZodObject<{
88
- table: z.ZodString;
89
- column: z.ZodString;
90
- }, z.core.$strict>;
91
- }, z.core.$strict>>;
92
- }, z.core.$strict>>;
93
- fieldBindings: z.ZodRecord<z.ZodString, z.ZodObject<{
94
- from: z.ZodObject<{
95
- table: z.ZodString;
96
- column: z.ZodString;
97
- }, z.core.$strict>;
98
- }, z.core.$strict>>;
99
- identity: z.ZodUnion<readonly [z.ZodObject<{
100
- kind: z.ZodLiteral<"base_pk">;
101
- column: z.ZodOptional<z.ZodString>;
102
- }, z.core.$strict>, z.ZodObject<{
103
- kind: z.ZodLiteral<"column">;
104
- from: z.ZodObject<{
105
- table: z.ZodString;
106
- column: z.ZodString;
107
- }, z.core.$strict>;
108
- }, z.core.$strict>, z.ZodObject<{
109
- kind: z.ZodLiteral<"composite">;
110
- parts: z.ZodArray<z.ZodObject<{
111
- table: z.ZodString;
112
- column: z.ZodString;
113
- }, z.core.$strict>>;
114
- }, z.core.$strict>]>;
115
- }, z.core.$strict>;
116
- type ProjectionMapping = z.infer<typeof projectionSchema>;
117
- /**
118
- * Every column ref an identity depends on. `basePkColumn` is the base table's
119
- * discovered PK, used only when a `base_pk` identity omits an explicit column.
120
- */
121
- declare function identityRefs(identity: ProjectionIdentity, basePkColumn: string): ProjectionRef[];
122
- //#endregion
123
- //#region src/mappings-config.d.ts
124
- /**
125
- * Mappings → Entity Config bridge.
126
- *
127
- * `crm_entity_mappings` rows are the single source of truth for how a host
128
- * schema maps onto Clivly's CRM concepts. This module compiles those rows into
129
- * a `ClivlyEntitiesConfig` — the contract the view compiler and sync engine
130
- * consume — so the persisted mapping and the runtime pipeline never diverge.
131
- *
132
- * The row model has no explicit entity-key column (it's keyed by
133
- * `sourceTable + targetConcept + role`), but the config's `relationships`
134
- * reference other entities *by key*. This builder therefore derives a stable
135
- * key per row and resolves each relationship's `entity` reference through the
136
- * same derivation — so a relationship stored as `entity: "<relatedTable>"`
137
- * (the shape `mappings.suggest` produces) resolves to the right entity.
138
- */
139
- /**
140
- * A persisted `crm_entity_mappings` row, narrowed to the columns the builder
141
- * reads. Structurally compatible with the Drizzle row (jsonb columns typed
142
- * loosely) so the API layer can pass `db.select()` results straight in.
143
- */
144
- interface EntityMappingRow {
145
- fieldMap: Record<string, string>;
146
- filter?: Record<string, unknown> | null;
147
- /**
148
- * Advanced mapping: a base table plus explicit joins. When set, this — not
149
- * `fieldMap` — is the authored source of truth, and `sourceTable` merely
150
- * mirrors `projection.baseTable`.
151
- */
152
- projection?: ProjectionMapping | null;
153
- relationships?: Record<string, unknown> | null;
154
- role?: string | null;
155
- sourceTable: string;
156
- status?: string | null;
157
- targetConcept: string;
158
- targetObjectTypeId?: string | null;
159
- }
160
- /**
161
- * Compile persisted mapping rows into a `ClivlyEntitiesConfig`. Only `active`
162
- * rows with at least one mapped field are included; disabled/suggested rows and
163
- * unmapped rows are skipped. Returns `{ entities: {} }` when nothing is
164
- * eligible — a no-op the view compiler and sync engine both tolerate.
165
- */
166
- declare function mappingsToEntitiesConfig(rows: EntityMappingRow[]): ClivlyEntitiesConfig;
167
- //#endregion
168
- export { ProjectionIdentity as a, ProjectionRef as c, ProjectionFieldBinding as i, identityRefs as l, mappingsToEntitiesConfig as n, ProjectionJoin as o, BASE_REF as r, ProjectionMapping as s, EntityMappingRow as t, projectionSchema as u };