@clivly/core 0.11.0-next.0 → 0.12.0

package/dist/types.d.mts

@@ -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;
@@ -40,19 +40,49 @@ interface Contact {
   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;
@@ -62,9 +92,23 @@ interface Deal {
   owner: string | null;
   position: number | null;
   stage: DealStage;
+  /**
+   * When a human last moved this deal by hand. Non-null means stage derivation
+   * no longer touches it, so a board must be able to mark it as overridden and
+   * offer a way back — otherwise an overridden deal is indistinguishable from
+   * one the rules simply never matched.
+   */
+  stageOverrideAt: Date | null;
   value: number;
+  /**
+   * When a human last set this deal's value by hand. Non-null means value
+   * derivation no longer touches it. Mirrors {@link Deal.stageOverrideAt} — and
+   * needs the same visibility, since an honoured-but-invisible override reads
+   * as a stuck deal rather than a pinned one.
+   */
+  valueOverrideAt: Date | null;
 }
-interface Task {
+export interface Task {
   archivedAt: Date | null;
   assignee: string | null;
   completedAt: Date | null;
@@ -81,7 +125,7 @@ interface Task {
   status: TaskStatus;
   title: string;
 }
-interface Note {
+export interface Note {
   archivedAt: Date | null;
   author: string | null;
   body: string;
@@ -96,7 +140,7 @@ interface Note {
   title: string;
   updatedAt: Date;
 }
-interface Activity {
+export interface Activity {
   actor: string | null;
   contactId: string | null;
   createdAt: Date;
@@ -105,7 +149,7 @@ interface Activity {
   summary: string;
   type: ActivityType;
 }
-interface CreateContactInput {
+export interface CreateContactInput {
   companyId?: string;
   email: string;
   name: string;
@@ -113,7 +157,7 @@ interface CreateContactInput {
   status?: ContactStatus;
   title?: string;
 }
-interface UpdateContactInput {
+export interface UpdateContactInput {
   companyId?: string | null;
   email?: string;
   name?: string;
@@ -121,13 +165,25 @@ interface UpdateContactInput {
   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;
@@ -135,7 +191,7 @@ interface CreateDealInput {
   stage?: DealStage;
   value?: number;
 }
-interface UpdateDealInput {
+export interface UpdateDealInput {
   closeDate?: Date | null;
   contactId?: string | null;
   name?: string;
@@ -143,7 +199,7 @@ interface UpdateDealInput {
   stage?: DealStage;
   value?: number;
 }
-interface CreateTaskInput {
+export interface CreateTaskInput {
   assignee?: string;
   createdBy?: string;
   description?: string;
@@ -153,7 +209,7 @@ interface CreateTaskInput {
   priority?: TaskPriority;
   title: string;
 }
-interface UpdateTaskInput {
+export interface UpdateTaskInput {
   assignee?: string | null;
   description?: string | null;
   dueAt?: Date | null;
@@ -162,20 +218,64 @@ 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 {
+/**
+ * One page of a keyset-paginated read.
+ *
+ * Keyset, not offset: `LIMIT/OFFSET` re-scans every skipped row, so page 200
+ * costs 200 pages of work, and a row inserted mid-listing shifts everything
+ * after it — the reader sees a record twice or never. A cursor anchored to
+ * `(createdAt, id)` is stable under concurrent writes and costs the same at
+ * page 1 and page 200.
+ *
+ * `audit.list` already does this; these types generalise its shape so the CRM
+ * lists cannot drift into a second convention.
+ */
+export interface PageRequest {
+  /** Opaque `${createdAtISO}|${id}`. Rows strictly older than this. */
+  cursor?: string;
+  limit?: number;
+}
+export interface Page<T> {
+  /** Null when this is the last page. */
+  nextCursor: string | null;
+  rows: T[];
+}
+export interface CompanyFilters {
+  /** See {@link ContactFilters.excludeArchived}. */
+  excludeArchived?: boolean;
+  source?: RecordSource;
+}
+export interface TaskFilters {
   assignee?: string;
   entityId?: string;
   entityType?: TaskEntityType;
@@ -184,5 +284,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

package/dist/view-compiler.d.cts

@@ -1,7 +1,7 @@
-import { a as ClivlyEntitiesConfig } from "./entity-config-Ddgukq_E.cjs";
+import { a as ClivlyEntitiesConfig } from "./entity-config-OhC4Otkz.cjs";
 //#region src/view-compiler.d.ts
-declare const DEFAULT_VIEW_PREFIX = "crm_src_";
-interface CompileOptions {
+export declare const DEFAULT_VIEW_PREFIX = "crm_src_";
+export interface CompileOptions {
   /**
    * Optional tenant-scoping predicate ANDed into every view's WHERE, e.g.
    * `{ column: "workspace_id", value: "ws_123" }`. Column must exist on the
@@ -29,7 +29,7 @@ interface CompileOptions {
   /** View name prefix. Defaults to `crm_src_`. */
   viewPrefix?: string;
 }
-interface CompiledView {
+export interface CompiledView {
   /** Output column names in SELECT order (`id`, mapped fields, then `<rel>_ref`s). */
   columns: string[];
   concept: string;
@@ -52,12 +52,12 @@ interface CompiledView {
  * (`reloptions.c`) — no mention of Clivly, the option, or the version. The
  * compiler cannot catch this itself because the host executes the SQL.
  */
-declare function explainViewExecutionError(error: unknown): string | undefined;
-declare function compileEntityView(config: ClivlyEntitiesConfig, entityKey: string, options?: CompileOptions): CompiledView;
+export declare function explainViewExecutionError(error: unknown): string | undefined;
+export declare function compileEntityView(config: ClivlyEntitiesConfig, entityKey: string, options?: CompileOptions): CompiledView;
 /** Compile every entity in the config into its view, in declaration order. */
-declare function compileEntityViews(config: ClivlyEntitiesConfig, options?: CompileOptions): CompiledView[];
+export declare function compileEntityViews(config: ClivlyEntitiesConfig, options?: CompileOptions): CompiledView[];
 /** The outcome of dry-running one entity's compiled view against the host. */
-interface ExplainResult {
+export interface ExplainResult {
   entityKey: string;
   /** The runner's error message when `ok` is false. */
   error?: string;
@@ -76,6 +76,5 @@ interface ExplainResult {
  * transaction it rolls back, or by `EXPLAIN`-ing the statement — since the
  * compiled SQL is a `CREATE OR REPLACE VIEW`.
  */
-declare function explainEntitiesConfig(config: ClivlyEntitiesConfig, run: (sql: string) => Promise<unknown>, options?: CompileOptions): Promise<ExplainResult[]>;
-//#endregion
-export { CompileOptions, CompiledView, DEFAULT_VIEW_PREFIX, ExplainResult, compileEntityView, compileEntityViews, explainEntitiesConfig, explainViewExecutionError };
+export declare function explainEntitiesConfig(config: ClivlyEntitiesConfig, run: (sql: string) => Promise<unknown>, options?: CompileOptions): Promise<ExplainResult[]>;
+//#endregion

package/dist/view-compiler.d.mts

@@ -1,7 +1,7 @@
-import { a as ClivlyEntitiesConfig } from "./entity-config-Ddgukq_E.mjs";
+import { a as ClivlyEntitiesConfig } from "./entity-config-OhC4Otkz.mjs";
 //#region src/view-compiler.d.ts
-declare const DEFAULT_VIEW_PREFIX = "crm_src_";
-interface CompileOptions {
+export declare const DEFAULT_VIEW_PREFIX = "crm_src_";
+export interface CompileOptions {
   /**
    * Optional tenant-scoping predicate ANDed into every view's WHERE, e.g.
    * `{ column: "workspace_id", value: "ws_123" }`. Column must exist on the
@@ -29,7 +29,7 @@ interface CompileOptions {
   /** View name prefix. Defaults to `crm_src_`. */
   viewPrefix?: string;
 }
-interface CompiledView {
+export interface CompiledView {
   /** Output column names in SELECT order (`id`, mapped fields, then `<rel>_ref`s). */
   columns: string[];
   concept: string;
@@ -52,12 +52,12 @@ interface CompiledView {
  * (`reloptions.c`) — no mention of Clivly, the option, or the version. The
  * compiler cannot catch this itself because the host executes the SQL.
  */
-declare function explainViewExecutionError(error: unknown): string | undefined;
-declare function compileEntityView(config: ClivlyEntitiesConfig, entityKey: string, options?: CompileOptions): CompiledView;
+export declare function explainViewExecutionError(error: unknown): string | undefined;
+export declare function compileEntityView(config: ClivlyEntitiesConfig, entityKey: string, options?: CompileOptions): CompiledView;
 /** Compile every entity in the config into its view, in declaration order. */
-declare function compileEntityViews(config: ClivlyEntitiesConfig, options?: CompileOptions): CompiledView[];
+export declare function compileEntityViews(config: ClivlyEntitiesConfig, options?: CompileOptions): CompiledView[];
 /** The outcome of dry-running one entity's compiled view against the host. */
-interface ExplainResult {
+export interface ExplainResult {
   entityKey: string;
   /** The runner's error message when `ok` is false. */
   error?: string;
@@ -76,6 +76,5 @@ interface ExplainResult {
  * transaction it rolls back, or by `EXPLAIN`-ing the statement — since the
  * compiled SQL is a `CREATE OR REPLACE VIEW`.
  */
-declare function explainEntitiesConfig(config: ClivlyEntitiesConfig, run: (sql: string) => Promise<unknown>, options?: CompileOptions): Promise<ExplainResult[]>;
-//#endregion
-export { CompileOptions, CompiledView, DEFAULT_VIEW_PREFIX, ExplainResult, compileEntityView, compileEntityViews, explainEntitiesConfig, explainViewExecutionError };
+export declare function explainEntitiesConfig(config: ClivlyEntitiesConfig, run: (sql: string) => Promise<unknown>, options?: CompileOptions): Promise<ExplainResult[]>;
+//#endregion

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clivly/core",
-  "version": "0.11.0-next.0",
+  "version": "0.12.0",
   "private": false,
   "description": "ORM/auth-agnostic CRM adapter contracts and shared domain types for Clivly.",
   "license": "MIT",