clivly 0.9.1 → 0.9.3

package/{mappings-config-DNaYGyKN.mjs → mappings-config-B1b1HVBg.mjs}

@@ -1,4 +1,4 @@
-import { t as CANONICAL_FIELDS } from "./entity-config-D08zAeFY.mjs";
+import { t as CANONICAL_FIELDS } from "./entity-config-kUHri9yA.mjs";
 //#region ../core/src/mappings-config.ts
 const RESERVED_FIELD = "id";
 /**
@@ -121,5 +121,28 @@ function mappingsToEntitiesConfig(rows) {
 	for (const { row, key } of assigned) entities[key] = buildEntity(row, refIndex);
 	return { entities };
 }
+const CUSTOM_CONCEPT = "custom";
+function entitiesToMappings(config) {
+	const rows = [];
+	for (const [entityKey, entity] of Object.entries(config.entities)) {
+		const row = {
+			entityKey,
+			sourceTable: entity.projection?.baseTable ?? entity.source,
+			targetConcept: entity.concept,
+			role: entity.role ?? DEFAULT_ROLE,
+			fieldMap: entity.projection ? {} : entity.fields
+		};
+		if (entity.filter) row.filter = entity.filter;
+		if (entity.relationships) row.relationships = entity.relationships;
+		if (entity.projection) row.projection = entity.projection;
+		if (entity.concept === CUSTOM_CONCEPT) {
+			row.objectTypeSlug = entityKey;
+			if (entity.objectType) row.objectType = entity.objectType;
+		}
+		if (entity.targetObjectTypeId) row.targetObjectTypeId = entity.targetObjectTypeId;
+		rows.push(row);
+	}
+	return rows;
+}
 //#endregion
-export { mappingsToEntitiesConfig as t };
+export { mappingsToEntitiesConfig as n, entitiesToMappings as t };

package/{mappings-config-B1qNM8VL.d.cts → mappings-config-D9dsonoi.d.mts}

@@ -1,4 +1,4 @@
-import { M as ProjectionMapping, a as ClivlyEntitiesConfig } from "./entity-config-fKQhimtD.cjs";
+import { P as ProjectionMapping, a as ClivlyEntitiesConfig, h as FilterExpr, x as RelationshipsMap } from "./entity-config-B2RA53nw.mjs";
 //#region ../core/src/mappings-config.d.ts
 /**
  * Mappings → Entity Config bridge.
@@ -43,5 +43,43 @@ interface EntityMappingRow {
  * eligible — a no-op the view compiler and sync engine both tolerate.
  */
 declare function mappingsToEntitiesConfig(rows: EntityMappingRow[]): ClivlyEntitiesConfig;
+/**
+ * Entity Config → Mappings, the inverse of `mappingsToEntitiesConfig`.
+ *
+ * `objectType` in config creates the custom object but nothing creates the
+ * MAPPING, so config-as-code ended at a created object and a sync that stored
+ * nothing. This produces the rows that close that gap.
+ *
+ * The two shapes align column for column, with one asymmetry that cannot be
+ * resolved by naming: the row model has no entity-key column — a row is keyed by
+ * `(sourceTable, targetConcept, role)` — while a CUSTOM entity's key *is* its
+ * object type slug, and is routinely different from its source table
+ * ("client-accounts" derived from "accounts"). So the key travels explicitly on
+ * every row rather than being left for the reverse derivation to guess.
+ */
+interface MappingFromConfig {
+  /**
+   * The config entity key this row came from. Not a row column — the caller
+   * needs it to resolve a custom object type and to report what it wrote.
+   */
+  entityKey: string;
+  fieldMap: Record<string, string>;
+  filter?: FilterExpr;
+  /** Declared custom object, when the config declares one rather than pinning an id. */
+  objectType?: {
+    iconKey?: string;
+    name: string;
+    pluralName?: string;
+  };
+  /** The custom object type's slug — the entity key. Custom entities only. */
+  objectTypeSlug?: string;
+  projection?: ProjectionMapping;
+  relationships?: RelationshipsMap;
+  role: string;
+  sourceTable: string;
+  targetConcept: string;
+  targetObjectTypeId?: string;
+}
+declare function entitiesToMappings(config: ClivlyEntitiesConfig): MappingFromConfig[];
 //#endregion
-export { mappingsToEntitiesConfig as n, EntityMappingRow as t };
+export { mappingsToEntitiesConfig as i, MappingFromConfig as n, entitiesToMappings as r, EntityMappingRow as t };

package/{mappings-config-BChZsany.d.mts → mappings-config-RQLGx8ub.d.cts}

@@ -1,4 +1,4 @@
-import { M as ProjectionMapping, a as ClivlyEntitiesConfig } from "./entity-config-fKQhimtD.mjs";
+import { P as ProjectionMapping, a as ClivlyEntitiesConfig, h as FilterExpr, x as RelationshipsMap } from "./entity-config-B2RA53nw.cjs";
 //#region ../core/src/mappings-config.d.ts
 /**
  * Mappings → Entity Config bridge.
@@ -43,5 +43,43 @@ interface EntityMappingRow {
  * eligible — a no-op the view compiler and sync engine both tolerate.
  */
 declare function mappingsToEntitiesConfig(rows: EntityMappingRow[]): ClivlyEntitiesConfig;
+/**
+ * Entity Config → Mappings, the inverse of `mappingsToEntitiesConfig`.
+ *
+ * `objectType` in config creates the custom object but nothing creates the
+ * MAPPING, so config-as-code ended at a created object and a sync that stored
+ * nothing. This produces the rows that close that gap.
+ *
+ * The two shapes align column for column, with one asymmetry that cannot be
+ * resolved by naming: the row model has no entity-key column — a row is keyed by
+ * `(sourceTable, targetConcept, role)` — while a CUSTOM entity's key *is* its
+ * object type slug, and is routinely different from its source table
+ * ("client-accounts" derived from "accounts"). So the key travels explicitly on
+ * every row rather than being left for the reverse derivation to guess.
+ */
+interface MappingFromConfig {
+  /**
+   * The config entity key this row came from. Not a row column — the caller
+   * needs it to resolve a custom object type and to report what it wrote.
+   */
+  entityKey: string;
+  fieldMap: Record<string, string>;
+  filter?: FilterExpr;
+  /** Declared custom object, when the config declares one rather than pinning an id. */
+  objectType?: {
+    iconKey?: string;
+    name: string;
+    pluralName?: string;
+  };
+  /** The custom object type's slug — the entity key. Custom entities only. */
+  objectTypeSlug?: string;
+  projection?: ProjectionMapping;
+  relationships?: RelationshipsMap;
+  role: string;
+  sourceTable: string;
+  targetConcept: string;
+  targetObjectTypeId?: string;
+}
+declare function entitiesToMappings(config: ClivlyEntitiesConfig): MappingFromConfig[];
 //#endregion
-export { mappingsToEntitiesConfig as n, EntityMappingRow as t };
+export { mappingsToEntitiesConfig as i, MappingFromConfig as n, entitiesToMappings as r, EntityMappingRow as t };

package/{namespace-probe-BkUs8raG.d.mts → namespace-probe-BmdGnYMn.d.mts}

@@ -1,4 +1,5 @@
-import { a as ClivlyEntitiesConfig } from "./entity-config-fKQhimtD.mjs";
+import { a as ClivlyEntitiesConfig } from "./entity-config-B2RA53nw.mjs";
+import { r as IntegrationState } from "./integration-state-BK-riZnm.mjs";
 //#region ../sdk/src/drizzle-meta.d.ts
 declare const DRIZZLE_META: "__clivly_drizzle_source_meta__";
 interface DrizzleSourceMeta {
@@ -78,6 +79,12 @@ interface ClivlySDKConfig {
    * runtimes can supply their own.
    */
   env?: Record<string, string | undefined>;
+  /**
+   * Where this app is running: `local_dev`, `preview` or `production`. Reported
+   * on each heartbeat so the dashboard can name the environment it is watching.
+   * Inferred from platform variables and `NODE_ENV` when omitted.
+   */
+  environment?: "local_dev" | "preview" | "production";
   /**
    * 🚧 Not implemented in 0.1.x. Reserved options for tunnel mode and CRM
    * write-back — they have NO effect yet and land with the Cloudflare
@@ -112,6 +119,17 @@ interface ClivlySDKConfig {
    */
   namespaceReady?: boolean;
   orm?: string;
+  /**
+   * Presence transport override. HTTP remains the default until the recorded
+   * production rollout gate permits a WebSocket default; set `http` explicitly
+   * to keep the legacy transport after that rollout. Operators may also set
+   * `CLIVLY_PRESENCE_TRANSPORT` without changing application code.
+   */
+  presence?: {
+    /** Explicit release identity; platform deployment ids and commit SHAs follow. */
+    deploymentId?: string;
+    transport?: "http" | "websocket";
+  };
   /**
    * Network retry policy for outbound calls (heartbeat + sync push). Transient
    * failures (network errors, HTTP 429, HTTP 5xx) are retried with exponential
@@ -217,6 +235,26 @@ interface CreateChatSessionHandlerOptions {
    */
   resolveUser?: (req: Request) => Promise<ClivlyUser | null> | ClivlyUser | null;
 }
+/** One object type ensured by `ensureSchema`. */
+interface EnsuredObjectTypeResult {
+  /** True when this call created it, false when it already existed. */
+  created: boolean;
+  id: string;
+  slug: string;
+}
+/** One mapping ensured by `ensureSchema`. */
+interface EnsuredMappingResult {
+  created: boolean;
+  /** The config entity key this mapping came from. */
+  entityKey: string;
+  id: string;
+  /** True when an existing config-owned mapping's definition changed. */
+  updated: boolean;
+}
+interface EnsureSchemaResult {
+  mappings: EnsuredMappingResult[];
+  objectTypes: EnsuredObjectTypeResult[];
+}
 interface DoctorCheck {
   /** Human-readable outcome — what passed, or why it failed. */
   detail: string;
@@ -264,6 +302,12 @@ interface ClivlyConnectResult {
   retryable: boolean;
   /** HTTP status, or null when the request never completed (network error). */
   status: number | null;
+  /**
+   * The workspace's setup ladder, computed by the server. Present only on
+   * `ping()`, and null when the server is older than this field or could not
+   * read it — which the CLI renders as "unavailable", never as "not set up".
+   */
+  workspace?: IntegrationState | null;
 }
 interface SyncCursor {
   /** The row's id, breaking ties when timestamps collide. */
@@ -325,6 +369,31 @@ interface ClivlySDK {
   createClivlyHandler(): (req: Request) => Promise<Response>;
   /** Validate this setup end-to-end (read-only) before the first sync. */
   doctor(): Promise<DoctorReport>;
+  /**
+   * Create any custom object types the config declares that this workspace does
+   * not have yet, keyed by entity slug — so `clivly.config.ts` needs no
+   * dashboard-generated id. Create-only and idempotent.
+   *
+   * Resolves to the ensured objects (empty when the config declares none), or
+   * `null` when the request could not be delivered.
+   */
+  ensureCustomObjects(): Promise<{
+    slug: string;
+    id: string;
+    created: boolean;
+  }[] | null>;
+  /**
+   * Declare the whole schema this config describes — custom object types AND
+   * the mappings that make them receive rows. The superset of
+   * `ensureCustomObjects`, which creates the object container and nothing else.
+   *
+   * Resolves to `null` when the request could not be delivered (including
+   * against a server too old to have the route), and REJECTS when Clivly
+   * refuses the config — e.g. an entity that would overwrite a mapping managed
+   * in the dashboard. That distinction matters: unreachable is worth a retry,
+   * refused is worth reading.
+   */
+  ensureSchema(): Promise<EnsureSchemaResult | null>;
   /**
    * Send a single heartbeat now. Returns true on success. Kept for the keep-alive
    * loop and back-compat; use `connect()` when you need the failure reason.
@@ -357,7 +426,7 @@ interface ClivlySDK {
    */
   start(): Promise<void>;
   /** Stop the keep-alive loop. */
-  stop(): void;
+  stop(): Promise<void>;
   /**
    * Sync all configured sources now. `delta` (default) pages changed rows since
    * the last cursor; `full` pushes each complete entity so the server can
@@ -378,4 +447,4 @@ interface NamespaceIntrospector {
   sampleSelect(table: string): Promise<void>;
 }
 //#endregion
-export { ClivlyConnectResult as a, ClivlyUser as c, DiscoveredTable as d, DoctorCheck as f, ClivlyConnectReason as i, CreateChatSessionHandlerOptions as l, SyncSource as m, ChatSessionRequestBody as n, ClivlySDK as o, DoctorReport as p, ChatWidgetVisitor as r, ClivlySDKConfig as s, NamespaceIntrospector as t, CursorStore as u };
+export { SyncSource as _, ClivlyConnectResult as a, ClivlyUser as c, DiscoveredTable as d, DoctorCheck as f, EnsuredObjectTypeResult as g, EnsuredMappingResult as h, ClivlyConnectReason as i, CreateChatSessionHandlerOptions as l, EnsureSchemaResult as m, ChatSessionRequestBody as n, ClivlySDK as o, DoctorReport as p, ChatWidgetVisitor as r, ClivlySDKConfig as s, NamespaceIntrospector as t, CursorStore as u };

package/{namespace-probe-aRFmpU85.d.cts → namespace-probe-EYyxWZnf.d.cts}

@@ -1,4 +1,5 @@
-import { a as ClivlyEntitiesConfig } from "./entity-config-fKQhimtD.cjs";
+import { a as ClivlyEntitiesConfig } from "./entity-config-B2RA53nw.cjs";
+import { r as IntegrationState } from "./integration-state-BK-riZnm.cjs";
 //#region ../sdk/src/drizzle-meta.d.ts
 declare const DRIZZLE_META: "__clivly_drizzle_source_meta__";
 interface DrizzleSourceMeta {
@@ -78,6 +79,12 @@ interface ClivlySDKConfig {
    * runtimes can supply their own.
    */
   env?: Record<string, string | undefined>;
+  /**
+   * Where this app is running: `local_dev`, `preview` or `production`. Reported
+   * on each heartbeat so the dashboard can name the environment it is watching.
+   * Inferred from platform variables and `NODE_ENV` when omitted.
+   */
+  environment?: "local_dev" | "preview" | "production";
   /**
    * 🚧 Not implemented in 0.1.x. Reserved options for tunnel mode and CRM
    * write-back — they have NO effect yet and land with the Cloudflare
@@ -112,6 +119,17 @@ interface ClivlySDKConfig {
    */
   namespaceReady?: boolean;
   orm?: string;
+  /**
+   * Presence transport override. HTTP remains the default until the recorded
+   * production rollout gate permits a WebSocket default; set `http` explicitly
+   * to keep the legacy transport after that rollout. Operators may also set
+   * `CLIVLY_PRESENCE_TRANSPORT` without changing application code.
+   */
+  presence?: {
+    /** Explicit release identity; platform deployment ids and commit SHAs follow. */
+    deploymentId?: string;
+    transport?: "http" | "websocket";
+  };
   /**
    * Network retry policy for outbound calls (heartbeat + sync push). Transient
    * failures (network errors, HTTP 429, HTTP 5xx) are retried with exponential
@@ -217,6 +235,26 @@ interface CreateChatSessionHandlerOptions {
    */
   resolveUser?: (req: Request) => Promise<ClivlyUser | null> | ClivlyUser | null;
 }
+/** One object type ensured by `ensureSchema`. */
+interface EnsuredObjectTypeResult {
+  /** True when this call created it, false when it already existed. */
+  created: boolean;
+  id: string;
+  slug: string;
+}
+/** One mapping ensured by `ensureSchema`. */
+interface EnsuredMappingResult {
+  created: boolean;
+  /** The config entity key this mapping came from. */
+  entityKey: string;
+  id: string;
+  /** True when an existing config-owned mapping's definition changed. */
+  updated: boolean;
+}
+interface EnsureSchemaResult {
+  mappings: EnsuredMappingResult[];
+  objectTypes: EnsuredObjectTypeResult[];
+}
 interface DoctorCheck {
   /** Human-readable outcome — what passed, or why it failed. */
   detail: string;
@@ -264,6 +302,12 @@ interface ClivlyConnectResult {
   retryable: boolean;
   /** HTTP status, or null when the request never completed (network error). */
   status: number | null;
+  /**
+   * The workspace's setup ladder, computed by the server. Present only on
+   * `ping()`, and null when the server is older than this field or could not
+   * read it — which the CLI renders as "unavailable", never as "not set up".
+   */
+  workspace?: IntegrationState | null;
 }
 interface SyncCursor {
   /** The row's id, breaking ties when timestamps collide. */
@@ -325,6 +369,31 @@ interface ClivlySDK {
   createClivlyHandler(): (req: Request) => Promise<Response>;
   /** Validate this setup end-to-end (read-only) before the first sync. */
   doctor(): Promise<DoctorReport>;
+  /**
+   * Create any custom object types the config declares that this workspace does
+   * not have yet, keyed by entity slug — so `clivly.config.ts` needs no
+   * dashboard-generated id. Create-only and idempotent.
+   *
+   * Resolves to the ensured objects (empty when the config declares none), or
+   * `null` when the request could not be delivered.
+   */
+  ensureCustomObjects(): Promise<{
+    slug: string;
+    id: string;
+    created: boolean;
+  }[] | null>;
+  /**
+   * Declare the whole schema this config describes — custom object types AND
+   * the mappings that make them receive rows. The superset of
+   * `ensureCustomObjects`, which creates the object container and nothing else.
+   *
+   * Resolves to `null` when the request could not be delivered (including
+   * against a server too old to have the route), and REJECTS when Clivly
+   * refuses the config — e.g. an entity that would overwrite a mapping managed
+   * in the dashboard. That distinction matters: unreachable is worth a retry,
+   * refused is worth reading.
+   */
+  ensureSchema(): Promise<EnsureSchemaResult | null>;
   /**
    * Send a single heartbeat now. Returns true on success. Kept for the keep-alive
    * loop and back-compat; use `connect()` when you need the failure reason.
@@ -357,7 +426,7 @@ interface ClivlySDK {
    */
   start(): Promise<void>;
   /** Stop the keep-alive loop. */
-  stop(): void;
+  stop(): Promise<void>;
   /**
    * Sync all configured sources now. `delta` (default) pages changed rows since
    * the last cursor; `full` pushes each complete entity so the server can
@@ -378,4 +447,4 @@ interface NamespaceIntrospector {
   sampleSelect(table: string): Promise<void>;
 }
 //#endregion
-export { ClivlyConnectResult as a, ClivlyUser as c, DiscoveredTable as d, DoctorCheck as f, ClivlyConnectReason as i, CreateChatSessionHandlerOptions as l, SyncSource as m, ChatSessionRequestBody as n, ClivlySDK as o, DoctorReport as p, ChatWidgetVisitor as r, ClivlySDKConfig as s, NamespaceIntrospector as t, CursorStore as u };
+export { SyncSource as _, ClivlyConnectResult as a, ClivlyUser as c, DiscoveredTable as d, DoctorCheck as f, EnsuredObjectTypeResult as g, EnsuredMappingResult as h, ClivlyConnectReason as i, CreateChatSessionHandlerOptions as l, EnsureSchemaResult as m, ChatSessionRequestBody as n, ClivlySDK as o, DoctorReport as p, ChatWidgetVisitor as r, ClivlySDKConfig as s, NamespaceIntrospector as t, CursorStore as u };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clivly",
-  "version": "0.9.1",
+  "version": "0.9.3",
   "private": false,
   "type": "module",
   "description": "Clivly CLI — scaffold a CRM into your app (clivly init).",