@clivly/core 0.10.9 → 0.11.0

package/dist/sync-engine.d.cts

@@ -1,4 +1,4 @@
-import { a as ClivlyEntitiesConfig } from "./entity-config-ChHLozko.cjs";
+import { a as ClivlyEntitiesConfig } from "./entity-config-OhC4Otkz.cjs";
 import { CompileOptions, CompiledView } from "./view-compiler.cjs";
 //#region src/sync-engine.d.ts
 /**
@@ -19,7 +19,7 @@ import { CompileOptions, CompiledView } from "./view-compiler.cjs";
  * package provides the concrete store.
  */
 /** A row read from a compiled view (what Postgres returns). */
-interface SourceRow {
+export interface SourceRow {
   /** Host-side company key from `<relationship>_ref`; resolved before persist. */
   companyRef?: string | null;
   /** Mapped identity fields (clivly field → value). */
@@ -28,14 +28,14 @@ interface SourceRow {
   sourceRef: string;
 }
 /** An existing mirror row, as far as reconciliation needs to know. */
-interface MirrorRecord {
+export interface MirrorRecord {
   archivedAt: Date | null;
   /** Host-side company key; only consulted in composite (join-table) mode. */
   companyRef: string | null;
   id: string;
   sourceRef: string;
 }
-type SyncAction = {
+export type SyncAction = {
   kind: "create";
   sourceRef: string;
   fields: Record<string, string | null>;
@@ -58,7 +58,7 @@ type SyncAction = {
   sourceRef: string;
 };
 /** A persist action with the company ref resolved to a `crm_companies.id`. */
-type PersistAction = {
+export type PersistAction = {
   kind: "create";
   sourceRef: string;
   fields: Record<string, string | null>;
@@ -99,11 +99,11 @@ type PersistAction = {
  * person in several companies materializes one mirror row per company and a
  * single membership leaving archives only that one row.
  */
-declare function reconcile(source: SourceRow[], mirror: MirrorRecord[], opts?: {
+export declare function reconcile(source: SourceRow[], mirror: MirrorRecord[], opts?: {
   composite?: boolean;
 }): SyncAction[];
 /** DB I/O port. The concrete store lives in the SDK/drizzle package. */
-interface SyncStore {
+export interface SyncStore {
   /** Current mirror rows for a concept + role (including archived). */
   listMirror(input: {
     concept: string;
@@ -129,7 +129,7 @@ interface SyncStore {
   /** Map host-side company refs → `crm_companies.id` (already-synced companies only). */
   resolveCompanyRefs(refs: string[]): Promise<Map<string, string>>;
 }
-interface EntitySyncResult {
+export interface EntitySyncResult {
   archived: number;
   concept: string;
   created: number;
@@ -138,7 +138,7 @@ interface EntitySyncResult {
   role: string;
   updated: number;
 }
-interface SyncResult {
+export interface SyncResult {
   entities: EntitySyncResult[];
   totals: {
     created: number;
@@ -151,12 +151,12 @@ interface SyncResult {
  * Run a full sync: compile the config's views, then reconcile + persist each,
  * companies first. Returns per-entity and total action counts.
  */
-declare function runSync(config: ClivlyEntitiesConfig, store: SyncStore, options?: CompileOptions): Promise<SyncResult>;
-interface PreviewWarning {
+export declare function runSync(config: ClivlyEntitiesConfig, store: SyncStore, options?: CompileOptions): Promise<SyncResult>;
+export interface PreviewWarning {
   field?: string;
   message: string;
 }
-interface PreviewResult {
+export interface PreviewResult {
   rows: SourceRow[];
   sampledCount: number;
   warnings: PreviewWarning[];
@@ -167,7 +167,7 @@ interface PreviewResult {
  * a required field empty in ≥1 row → `K/N` form; an optional field empty in
  * ALL rows → all-empty form; zero source rows → a single table-level warning.
  */
-declare function computeSampleWarnings(rows: SourceRow[], requiredFields: string[], sourceTable: string): PreviewWarning[];
+export declare function computeSampleWarnings(rows: SourceRow[], requiredFields: string[], sourceTable: string): PreviewWarning[];
 /**
  * Zero-write preview: read ≤`limit` rows through the compiled view (a pure
  * SELECT whose SQL already projects each row into its mapped fields) and
@@ -175,10 +175,9 @@ declare function computeSampleWarnings(rows: SourceRow[], requiredFields: string
  * so it can never mutate the mirror. The distinct, write-one-row sibling is
  * `runSync`'s sample mode (T13).
  */
-declare function previewSync(store: SyncStore, view: CompiledView, opts: {
+export declare function previewSync(store: SyncStore, view: CompiledView, opts: {
   limit: number;
   requiredFields: string[];
   sourceTable: string;
 }): Promise<PreviewResult>;
-//#endregion
-export { EntitySyncResult, MirrorRecord, PersistAction, PreviewResult, PreviewWarning, SourceRow, SyncAction, SyncResult, SyncStore, computeSampleWarnings, previewSync, reconcile, runSync };
+//#endregion

package/dist/sync-engine.d.mts

@@ -1,4 +1,4 @@
-import { a as ClivlyEntitiesConfig } from "./entity-config-ChHLozko.mjs";
+import { a as ClivlyEntitiesConfig } from "./entity-config-OhC4Otkz.mjs";
 import { CompileOptions, CompiledView } from "./view-compiler.mjs";
 //#region src/sync-engine.d.ts
 /**
@@ -19,7 +19,7 @@ import { CompileOptions, CompiledView } from "./view-compiler.mjs";
  * package provides the concrete store.
  */
 /** A row read from a compiled view (what Postgres returns). */
-interface SourceRow {
+export interface SourceRow {
   /** Host-side company key from `<relationship>_ref`; resolved before persist. */
   companyRef?: string | null;
   /** Mapped identity fields (clivly field → value). */
@@ -28,14 +28,14 @@ interface SourceRow {
   sourceRef: string;
 }
 /** An existing mirror row, as far as reconciliation needs to know. */
-interface MirrorRecord {
+export interface MirrorRecord {
   archivedAt: Date | null;
   /** Host-side company key; only consulted in composite (join-table) mode. */
   companyRef: string | null;
   id: string;
   sourceRef: string;
 }
-type SyncAction = {
+export type SyncAction = {
   kind: "create";
   sourceRef: string;
   fields: Record<string, string | null>;
@@ -58,7 +58,7 @@ type SyncAction = {
   sourceRef: string;
 };
 /** A persist action with the company ref resolved to a `crm_companies.id`. */
-type PersistAction = {
+export type PersistAction = {
   kind: "create";
   sourceRef: string;
   fields: Record<string, string | null>;
@@ -99,11 +99,11 @@ type PersistAction = {
  * person in several companies materializes one mirror row per company and a
  * single membership leaving archives only that one row.
  */
-declare function reconcile(source: SourceRow[], mirror: MirrorRecord[], opts?: {
+export declare function reconcile(source: SourceRow[], mirror: MirrorRecord[], opts?: {
   composite?: boolean;
 }): SyncAction[];
 /** DB I/O port. The concrete store lives in the SDK/drizzle package. */
-interface SyncStore {
+export interface SyncStore {
   /** Current mirror rows for a concept + role (including archived). */
   listMirror(input: {
     concept: string;
@@ -129,7 +129,7 @@ interface SyncStore {
   /** Map host-side company refs → `crm_companies.id` (already-synced companies only). */
   resolveCompanyRefs(refs: string[]): Promise<Map<string, string>>;
 }
-interface EntitySyncResult {
+export interface EntitySyncResult {
   archived: number;
   concept: string;
   created: number;
@@ -138,7 +138,7 @@ interface EntitySyncResult {
   role: string;
   updated: number;
 }
-interface SyncResult {
+export interface SyncResult {
   entities: EntitySyncResult[];
   totals: {
     created: number;
@@ -151,12 +151,12 @@ interface SyncResult {
  * Run a full sync: compile the config's views, then reconcile + persist each,
  * companies first. Returns per-entity and total action counts.
  */
-declare function runSync(config: ClivlyEntitiesConfig, store: SyncStore, options?: CompileOptions): Promise<SyncResult>;
-interface PreviewWarning {
+export declare function runSync(config: ClivlyEntitiesConfig, store: SyncStore, options?: CompileOptions): Promise<SyncResult>;
+export interface PreviewWarning {
   field?: string;
   message: string;
 }
-interface PreviewResult {
+export interface PreviewResult {
   rows: SourceRow[];
   sampledCount: number;
   warnings: PreviewWarning[];
@@ -167,7 +167,7 @@ interface PreviewResult {
  * a required field empty in ≥1 row → `K/N` form; an optional field empty in
  * ALL rows → all-empty form; zero source rows → a single table-level warning.
  */
-declare function computeSampleWarnings(rows: SourceRow[], requiredFields: string[], sourceTable: string): PreviewWarning[];
+export declare function computeSampleWarnings(rows: SourceRow[], requiredFields: string[], sourceTable: string): PreviewWarning[];
 /**
  * Zero-write preview: read ≤`limit` rows through the compiled view (a pure
  * SELECT whose SQL already projects each row into its mapped fields) and
@@ -175,10 +175,9 @@ declare function computeSampleWarnings(rows: SourceRow[], requiredFields: string
  * so it can never mutate the mirror. The distinct, write-one-row sibling is
  * `runSync`'s sample mode (T13).
  */
-declare function previewSync(store: SyncStore, view: CompiledView, opts: {
+export declare function previewSync(store: SyncStore, view: CompiledView, opts: {
   limit: number;
   requiredFields: string[];
   sourceTable: string;
 }): Promise<PreviewResult>;
-//#endregion
-export { EntitySyncResult, MirrorRecord, PersistAction, PreviewResult, PreviewWarning, SourceRow, SyncAction, SyncResult, SyncStore, computeSampleWarnings, previewSync, reconcile, runSync };
+//#endregion

package/dist/types.d.cts

@@ -1,14 +1,14 @@
 //#region src/types.d.ts
-type ContactStatus = "lead" | "active" | "customer" | "churned";
-type DealStage = string;
-type StageType = "open" | "won" | "lost";
-type PipelineKind = "standard" | "recurring";
-type ValueInterval = "one_time" | "monthly" | "annual";
+export type ContactStatus = "lead" | "active" | "customer" | "churned";
+export type DealStage = string;
+export type StageType = "open" | "won" | "lost";
+export type PipelineKind = "standard" | "recurring";
+export type ValueInterval = "one_time" | "monthly" | "annual";
 /** Named once so SQL predicates and UI fallbacks cannot drift apart. */
-declare const OPEN_STAGE_TYPE: "open";
+export declare const OPEN_STAGE_TYPE: "open";
 /** A closed deal is a historical fact: automation never reopens one. */
-declare function isClosedStageType(type: StageType): boolean;
-interface PipelineStageConfig {
+export declare function isClosedStageType(type: StageType): boolean;
+export interface PipelineStageConfig {
   color: string | null;
   id: string;
   key: DealStage;
@@ -17,7 +17,7 @@ interface PipelineStageConfig {
   type: StageType;
   valueFixed: number | null;
 }
-interface PipelineConfig {
+export interface PipelineConfig {
   id: string;
   isDefault: boolean;
   kind: PipelineKind;
@@ -26,12 +26,12 @@ interface PipelineConfig {
   sourceMappingId: string | null;
   stages: PipelineStageConfig[];
 }
-type TaskStatus = "todo" | "in_progress" | "done" | "cancelled";
-type TaskPriority = "low" | "medium" | "high";
-type TaskEntityType = "contact" | "company" | "deal";
-type ActivityType = "note" | "email" | "task" | "deal" | "call";
-type CrmRole = "owner" | "admin" | "member" | "developer" | "support_agent";
-interface Contact {
+export type TaskStatus = "todo" | "in_progress" | "done" | "cancelled";
+export type TaskPriority = "low" | "medium" | "high";
+export type TaskEntityType = "contact" | "company" | "custom" | "deal";
+export type ActivityType = "note" | "email" | "task" | "deal" | "call";
+export type CrmRole = "owner" | "admin" | "member" | "developer" | "support_agent";
+export interface Contact {
   companyId: string | null;
   createdAt: Date;
   email: string;
@@ -39,19 +39,50 @@ interface Contact {
   lastActivityAt: Date | null;
   name: string;
   orgId: string;
+  phone: string | null;
+  /**
+   * The host row this contact mirrors, or null when it was created in the CRM.
+   *
+   * Carried on the domain type because it decides whether a user may edit the
+   * identity fields: sync rewrites them from the host view on every run, so an
+   * edit to a sourced row would be silently reverted. See `host-owned-fields`.
+   */
+  sourceRef: string | null;
   status: ContactStatus;
   title: string | null;
 }
-interface Company {
+export interface Company {
+  /**
+   * How many non-archived contacts are attached to this company.
+   *
+   * Derived per read, never stored — distinct from {@link Company.size}, which
+   * is the mappable headcount of the business itself. A provider with 400 staff
+   * and 4 CRM contacts has `size: "400"` and `contactCount: 4`; conflating them
+   * would state a falsehood in the authoritative-looking direction.
+   */
+  contactCount: number;
   createdAt: Date;
   domain: string | null;
+  email: string | null;
   id: string;
   industry: string | null;
   name: string;
   orgId: string;
+  phone: string | null;
+  /**
+   * The one contact to talk to at this company, if chosen.
+   *
+   * Constrained to a contact of this same company, and cleared when that
+   * contact is archived — so a non-null value always names someone live and
+   * attached here. Unlike the other fields it is never host-owned: it is a CRM
+   * judgement, so it stays editable on synced rows.
+   */
+  primaryContactId: string | null;
   size: string | null;
+  /** See {@link Contact.sourceRef}. */
+  sourceRef: string | null;
 }
-interface Deal {
+export interface Deal {
   closeDate: Date | null;
   contactId: string | null;
   createdAt: Date;
@@ -63,7 +94,7 @@ interface Deal {
   stage: DealStage;
   value: number;
 }
-interface Task {
+export interface Task {
   archivedAt: Date | null;
   assignee: string | null;
   completedAt: Date | null;
@@ -80,7 +111,7 @@ interface Task {
   status: TaskStatus;
   title: string;
 }
-interface Note {
+export interface Note {
   archivedAt: Date | null;
   author: string | null;
   body: string;
@@ -95,7 +126,7 @@ interface Note {
   title: string;
   updatedAt: Date;
 }
-interface Activity {
+export interface Activity {
   actor: string | null;
   contactId: string | null;
   createdAt: Date;
@@ -104,27 +135,41 @@ interface Activity {
   summary: string;
   type: ActivityType;
 }
-interface CreateContactInput {
+export interface CreateContactInput {
   companyId?: string;
   email: string;
   name: string;
+  phone?: string;
   status?: ContactStatus;
   title?: string;
 }
-interface UpdateContactInput {
+export interface UpdateContactInput {
   companyId?: string | null;
   email?: string;
   name?: string;
+  phone?: string | null;
   status?: ContactStatus;
   title?: string | null;
 }
-interface CreateCompanyInput {
+export interface CreateCompanyInput {
   domain?: string;
+  email?: string;
   industry?: string;
   name: string;
+  phone?: string;
   size?: string;
 }
-interface CreateDealInput {
+export interface UpdateCompanyInput {
+  domain?: string | null;
+  email?: string | null;
+  industry?: string | null;
+  name?: string;
+  phone?: string | null;
+  /** Null clears the point of contact; see {@link Company.primaryContactId}. */
+  primaryContactId?: string | null;
+  size?: string | null;
+}
+export interface CreateDealInput {
   contactId?: string;
   name: string;
   owner?: string;
@@ -132,7 +177,7 @@ interface CreateDealInput {
   stage?: DealStage;
   value?: number;
 }
-interface UpdateDealInput {
+export interface UpdateDealInput {
   closeDate?: Date | null;
   contactId?: string | null;
   name?: string;
@@ -140,7 +185,7 @@ interface UpdateDealInput {
   stage?: DealStage;
   value?: number;
 }
-interface CreateTaskInput {
+export interface CreateTaskInput {
   assignee?: string;
   createdBy?: string;
   description?: string;
@@ -150,7 +195,7 @@ interface CreateTaskInput {
   priority?: TaskPriority;
   title: string;
 }
-interface UpdateTaskInput {
+export interface UpdateTaskInput {
   assignee?: string | null;
   description?: string | null;
   dueAt?: Date | null;
@@ -159,20 +204,42 @@ interface UpdateTaskInput {
   priority?: TaskPriority;
   title?: string;
 }
-interface CreateActivityInput {
+export interface CreateActivityInput {
   actor?: string;
   contactId?: string;
   summary: string;
   type: ActivityType;
 }
-type RecordSource = "all" | "synced";
-interface ContactFilters {
+export type RecordSource = "all" | "synced";
+export interface ContactFilters {
   companyId?: string;
+  /**
+   * Exclude archived rows. Defaults to false — the adapter returns everything
+   * — because most callers are lookup maps, not user-facing lists:
+   * `importContacts` builds its dedup set from this (hiding archived rows
+   * would resurrect a contact the user archived as a duplicate) and
+   * `deals.list` builds its contact-name map from it (an archived contact on
+   * a live deal would render blank).
+   *
+   * The user-facing `contacts.list` / `companies.list` routes opt in, because
+   * there `archiveContact` is the delete affordance and a row still visible
+   * after archiving reads as a failed delete.
+   *
+   * Independent of `source`: `source: "synced"` already excludes archived
+   * rows, since sync archives a row when it leaves the host view and such a
+   * row is no longer sync-provenanced.
+   */
+  excludeArchived?: boolean;
   search?: string;
   source?: RecordSource;
   status?: ContactStatus;
 }
-interface TaskFilters {
+export interface CompanyFilters {
+  /** See {@link ContactFilters.excludeArchived}. */
+  excludeArchived?: boolean;
+  source?: RecordSource;
+}
+export interface TaskFilters {
   assignee?: string;
   entityId?: string;
   entityType?: TaskEntityType;
@@ -181,5 +248,4 @@ interface TaskFilters {
   priority?: TaskPriority;
   status?: TaskStatus;
 }
-//#endregion
-export { Activity, ActivityType, Company, Contact, ContactFilters, ContactStatus, CreateActivityInput, CreateCompanyInput, CreateContactInput, CreateDealInput, CreateTaskInput, CrmRole, Deal, DealStage, Note, OPEN_STAGE_TYPE, PipelineConfig, PipelineKind, PipelineStageConfig, RecordSource, StageType, Task, TaskEntityType, TaskFilters, TaskPriority, TaskStatus, UpdateContactInput, UpdateDealInput, UpdateTaskInput, ValueInterval, isClosedStageType };
+//#endregion