clivly 0.14.1 → 0.15.0

package/README.md

@@ -245,9 +245,9 @@ would never load.
 
 The pairing endpoints are feature-flagged server-side
 (`CLIVLY_CLI_PAIRING_ENABLED`). **Clivly Cloud has pairing enabled**, so
-`clivly login` is the normal path there. The flag defaults to `false`, so a
-self-hosted backend must opt in — otherwise `clivly login` says so and exits
-non-zero.
+`clivly login` is the normal path there. Against a backend
+with the flag off, `clivly login` says so and exits non-zero; use the manual
+credential path below.
 
 #### Manual credential path
 

package/{adapter-B-iBMhl0.d.mts → adapter-BMAUq4hf.d.mts}

@@ -1,4 +1,4 @@
-import { A as UpdateCompanyInput, C as RecordSource, D as TaskFilters, M as UpdateDealInput, N as UpdateTaskInput, T as Task, a as Contact, c as CreateActivityInput, d as CreateDealInput, f as CreateTaskInput, i as CompanyFilters, j as UpdateContactInput, l as CreateCompanyInput, m as Deal, o as ContactFilters, r as Company, t as Activity, u as CreateContactInput, v as Page, y as PageRequest } from "./types-B17TWEOL.mjs";
+import { A as UpdateCompanyInput, C as RecordSource, D as TaskFilters, M as UpdateDealInput, N as UpdateTaskInput, T as Task, a as Contact, c as CreateActivityInput, d as CreateDealInput, f as CreateTaskInput, i as CompanyFilters, j as UpdateContactInput, l as CreateCompanyInput, m as Deal, o as ContactFilters, r as Company, t as Activity, u as CreateContactInput, v as Page, y as PageRequest } from "./types-CpAtAtxd.mjs";
 //#region ../core/src/adapter.d.ts
 /**
  * The contract every ORM implementation fulfils. `packages/drizzle` is the first
@@ -19,6 +19,20 @@ interface CRMAdapter {
   archiveContact(orgId: string, id: string): Promise<Contact>;
   archiveTask(orgId: string, id: string): Promise<Task>;
   completeTask(orgId: string, id: string): Promise<Task>;
+  /**
+   * How many contacts match `filters`, ignoring pagination entirely.
+   *
+   * Exists so a caller can state the size of a selection before acting on it —
+   * a bulk send has to say "this will go to N contacts", and the paged read
+   * cannot answer that: it knows only whether *another* page exists, never how
+   * many rows are behind it.
+   *
+   * Takes the same `ContactFilters` as {@link CRMAdapter.listContactsPage} and
+   * applies exactly the same predicates, so the count and the list can never
+   * disagree about what matches. It returns a number rather than rows, so it
+   * stays bounded however large the match is.
+   */
+  countContacts(orgId: string, filters?: ContactFilters): Promise<number>;
   createActivity(orgId: string, data: CreateActivityInput): Promise<Activity>;
   createCompany(orgId: string, data: CreateCompanyInput): Promise<Company>;
   createContact(orgId: string, data: CreateContactInput): Promise<Contact>;

package/{adapter-JpXSAnj-.d.cts → adapter-IH3r_I8v.d.cts}

@@ -1,4 +1,4 @@
-import { A as UpdateCompanyInput, C as RecordSource, D as TaskFilters, M as UpdateDealInput, N as UpdateTaskInput, T as Task, a as Contact, c as CreateActivityInput, d as CreateDealInput, f as CreateTaskInput, i as CompanyFilters, j as UpdateContactInput, l as CreateCompanyInput, m as Deal, o as ContactFilters, r as Company, t as Activity, u as CreateContactInput, v as Page, y as PageRequest } from "./types-B17TWEOL.cjs";
+import { A as UpdateCompanyInput, C as RecordSource, D as TaskFilters, M as UpdateDealInput, N as UpdateTaskInput, T as Task, a as Contact, c as CreateActivityInput, d as CreateDealInput, f as CreateTaskInput, i as CompanyFilters, j as UpdateContactInput, l as CreateCompanyInput, m as Deal, o as ContactFilters, r as Company, t as Activity, u as CreateContactInput, v as Page, y as PageRequest } from "./types-CpAtAtxd.cjs";
 //#region ../core/src/adapter.d.ts
 /**
  * The contract every ORM implementation fulfils. `packages/drizzle` is the first
@@ -19,6 +19,20 @@ interface CRMAdapter {
   archiveContact(orgId: string, id: string): Promise<Contact>;
   archiveTask(orgId: string, id: string): Promise<Task>;
   completeTask(orgId: string, id: string): Promise<Task>;
+  /**
+   * How many contacts match `filters`, ignoring pagination entirely.
+   *
+   * Exists so a caller can state the size of a selection before acting on it —
+   * a bulk send has to say "this will go to N contacts", and the paged read
+   * cannot answer that: it knows only whether *another* page exists, never how
+   * many rows are behind it.
+   *
+   * Takes the same `ContactFilters` as {@link CRMAdapter.listContactsPage} and
+   * applies exactly the same predicates, so the count and the list can never
+   * disagree about what matches. It returns a number rather than rows, so it
+   * stays bounded however large the match is.
+   */
+  countContacts(orgId: string, filters?: ContactFilters): Promise<number>;
   createActivity(orgId: string, data: CreateActivityInput): Promise<Activity>;
   createCompany(orgId: string, data: CreateCompanyInput): Promise<Company>;
   createContact(orgId: string, data: CreateContactInput): Promise<Contact>;

package/{auth-adapter-C6rDx3XH.d.mts → auth-adapter-Bt1GZiag.d.cts}

@@ -1,4 +1,4 @@
-import { p as CrmRole } from "./types-B17TWEOL.mjs";
+import { p as CrmRole } from "./types-CpAtAtxd.cjs";
 //#region ../core/src/auth-adapter.d.ts
 interface ClivlyUser {
   email: string;

package/{auth-adapter-Csk9KkvI.d.cts → auth-adapter-CHy273qb.d.mts}

@@ -1,4 +1,4 @@
-import { p as CrmRole } from "./types-B17TWEOL.cjs";
+import { p as CrmRole } from "./types-CpAtAtxd.mjs";
 //#region ../core/src/auth-adapter.d.ts
 interface ClivlyUser {
   email: string;

package/auth-better-auth.d.cts

@@ -1,4 +1,4 @@
-import { n as ClivlyUser, t as ClivlyAuthAdapter } from "./auth-adapter-Csk9KkvI.cjs";
+import { n as ClivlyUser, t as ClivlyAuthAdapter } from "./auth-adapter-Bt1GZiag.cjs";
 //#region ../auth-better-auth/src/map.d.ts
 interface BetterAuthLikeUser {
   email?: string | null;

package/auth-better-auth.d.mts

@@ -1,4 +1,4 @@
-import { n as ClivlyUser, t as ClivlyAuthAdapter } from "./auth-adapter-C6rDx3XH.mjs";
+import { n as ClivlyUser, t as ClivlyAuthAdapter } from "./auth-adapter-CHy273qb.mjs";
 //#region ../auth-better-auth/src/map.d.ts
 interface BetterAuthLikeUser {
   email?: string | null;

package/auth-clerk.d.cts

@@ -1,4 +1,4 @@
-import { n as ClivlyUser, t as ClivlyAuthAdapter } from "./auth-adapter-Csk9KkvI.cjs";
+import { n as ClivlyUser, t as ClivlyAuthAdapter } from "./auth-adapter-Bt1GZiag.cjs";
 //#region ../auth-clerk/src/map.d.ts
 interface ClerkLikeUser {
   emailAddresses?: Array<{

package/auth-clerk.d.mts

@@ -1,4 +1,4 @@
-import { n as ClivlyUser, t as ClivlyAuthAdapter } from "./auth-adapter-C6rDx3XH.mjs";
+import { n as ClivlyUser, t as ClivlyAuthAdapter } from "./auth-adapter-CHy273qb.mjs";
 //#region ../auth-clerk/src/map.d.ts
 interface ClerkLikeUser {
   emailAddresses?: Array<{

package/auth-workos.d.cts

@@ -1,4 +1,4 @@
-import { n as ClivlyUser, t as ClivlyAuthAdapter } from "./auth-adapter-Csk9KkvI.cjs";
+import { n as ClivlyUser, t as ClivlyAuthAdapter } from "./auth-adapter-Bt1GZiag.cjs";
 //#region ../auth-workos/src/map.d.ts
 interface WorkOSLikeUser {
   email: string;

package/auth-workos.d.mts

@@ -1,4 +1,4 @@
-import { n as ClivlyUser, t as ClivlyAuthAdapter } from "./auth-adapter-C6rDx3XH.mjs";
+import { n as ClivlyUser, t as ClivlyAuthAdapter } from "./auth-adapter-CHy273qb.mjs";
 //#region ../auth-workos/src/map.d.ts
 interface WorkOSLikeUser {
   email: string;

package/core-adapter.d.cts

@@ -1,2 +1,2 @@
-import { t as CRMAdapter } from "./adapter-JpXSAnj-.cjs";
+import { t as CRMAdapter } from "./adapter-IH3r_I8v.cjs";
 export { CRMAdapter };

package/core-adapter.d.mts

@@ -1,2 +1,2 @@
-import { t as CRMAdapter } from "./adapter-B-iBMhl0.mjs";
+import { t as CRMAdapter } from "./adapter-BMAUq4hf.mjs";
 export { CRMAdapter };

package/core-auth-adapter.d.cts

@@ -1,2 +1,2 @@
-import { a as authCustom, i as MembershipResolver, n as ClivlyUser, r as CrmMembership, t as ClivlyAuthAdapter } from "./auth-adapter-Csk9KkvI.cjs";
+import { a as authCustom, i as MembershipResolver, n as ClivlyUser, r as CrmMembership, t as ClivlyAuthAdapter } from "./auth-adapter-Bt1GZiag.cjs";
 export { ClivlyAuthAdapter, ClivlyUser, CrmMembership, MembershipResolver, authCustom };

package/core-auth-adapter.d.mts

@@ -1,2 +1,2 @@
-import { a as authCustom, i as MembershipResolver, n as ClivlyUser, r as CrmMembership, t as ClivlyAuthAdapter } from "./auth-adapter-C6rDx3XH.mjs";
+import { a as authCustom, i as MembershipResolver, n as ClivlyUser, r as CrmMembership, t as ClivlyAuthAdapter } from "./auth-adapter-CHy273qb.mjs";
 export { ClivlyAuthAdapter, ClivlyUser, CrmMembership, MembershipResolver, authCustom };

package/core-types.d.cts

@@ -1,2 +1,2 @@
-import { A as UpdateCompanyInput, C as RecordSource, D as TaskFilters, E as TaskEntityType, F as isClosedStageType, M as UpdateDealInput, N as UpdateTaskInput, O as TaskPriority, P as ValueInterval, S as PipelineStageConfig, T as Task, _ as OPEN_STAGE_TYPE, a as Contact, b as PipelineConfig, c as CreateActivityInput, d as CreateDealInput, f as CreateTaskInput, g as Note, h as DealStage, i as CompanyFilters, j as UpdateContactInput, k as TaskStatus, l as CreateCompanyInput, m as Deal, n as ActivityType, o as ContactFilters, p as CrmRole, r as Company, s as ContactStatus, t as Activity, u as CreateContactInput, v as Page, w as StageType, x as PipelineKind, y as PageRequest } from "./types-B17TWEOL.cjs";
+import { A as UpdateCompanyInput, C as RecordSource, D as TaskFilters, E as TaskEntityType, F as isClosedStageType, M as UpdateDealInput, N as UpdateTaskInput, O as TaskPriority, P as ValueInterval, S as PipelineStageConfig, T as Task, _ as OPEN_STAGE_TYPE, a as Contact, b as PipelineConfig, c as CreateActivityInput, d as CreateDealInput, f as CreateTaskInput, g as Note, h as DealStage, i as CompanyFilters, j as UpdateContactInput, k as TaskStatus, l as CreateCompanyInput, m as Deal, n as ActivityType, o as ContactFilters, p as CrmRole, r as Company, s as ContactStatus, t as Activity, u as CreateContactInput, v as Page, w as StageType, x as PipelineKind, y as PageRequest } from "./types-CpAtAtxd.cjs";
 export { Activity, ActivityType, Company, CompanyFilters, Contact, ContactFilters, ContactStatus, CreateActivityInput, CreateCompanyInput, CreateContactInput, CreateDealInput, CreateTaskInput, CrmRole, Deal, DealStage, Note, OPEN_STAGE_TYPE, Page, PageRequest, PipelineConfig, PipelineKind, PipelineStageConfig, RecordSource, StageType, Task, TaskEntityType, TaskFilters, TaskPriority, TaskStatus, UpdateCompanyInput, UpdateContactInput, UpdateDealInput, UpdateTaskInput, ValueInterval, isClosedStageType };

package/core-types.d.mts

@@ -1,2 +1,2 @@
-import { A as UpdateCompanyInput, C as RecordSource, D as TaskFilters, E as TaskEntityType, F as isClosedStageType, M as UpdateDealInput, N as UpdateTaskInput, O as TaskPriority, P as ValueInterval, S as PipelineStageConfig, T as Task, _ as OPEN_STAGE_TYPE, a as Contact, b as PipelineConfig, c as CreateActivityInput, d as CreateDealInput, f as CreateTaskInput, g as Note, h as DealStage, i as CompanyFilters, j as UpdateContactInput, k as TaskStatus, l as CreateCompanyInput, m as Deal, n as ActivityType, o as ContactFilters, p as CrmRole, r as Company, s as ContactStatus, t as Activity, u as CreateContactInput, v as Page, w as StageType, x as PipelineKind, y as PageRequest } from "./types-B17TWEOL.mjs";
+import { A as UpdateCompanyInput, C as RecordSource, D as TaskFilters, E as TaskEntityType, F as isClosedStageType, M as UpdateDealInput, N as UpdateTaskInput, O as TaskPriority, P as ValueInterval, S as PipelineStageConfig, T as Task, _ as OPEN_STAGE_TYPE, a as Contact, b as PipelineConfig, c as CreateActivityInput, d as CreateDealInput, f as CreateTaskInput, g as Note, h as DealStage, i as CompanyFilters, j as UpdateContactInput, k as TaskStatus, l as CreateCompanyInput, m as Deal, n as ActivityType, o as ContactFilters, p as CrmRole, r as Company, s as ContactStatus, t as Activity, u as CreateContactInput, v as Page, w as StageType, x as PipelineKind, y as PageRequest } from "./types-CpAtAtxd.mjs";
 export { Activity, ActivityType, Company, CompanyFilters, Contact, ContactFilters, ContactStatus, CreateActivityInput, CreateCompanyInput, CreateContactInput, CreateDealInput, CreateTaskInput, CrmRole, Deal, DealStage, Note, OPEN_STAGE_TYPE, Page, PageRequest, PipelineConfig, PipelineKind, PipelineStageConfig, RecordSource, StageType, Task, TaskEntityType, TaskFilters, TaskPriority, TaskStatus, UpdateCompanyInput, UpdateContactInput, UpdateDealInput, UpdateTaskInput, ValueInterval, isClosedStageType };

package/core.cjs

@@ -3,7 +3,7 @@ const require_projection = require("./projection-BELgANG2.cjs");
 const require_entity_config = require("./entity-config-BI4RYNKL.cjs");
 const require_mappings_config = require("./mappings-config-BCsRLohT.cjs");
 const require_auth_adapter = require("./auth-adapter-CiEXcweZ.cjs");
-const require_internal = require("./internal-BxtvxF7Z.cjs");
+const require_internal = require("./internal-DsArcqkP.cjs");
 const require_mapping_form = require("./mapping-form-BpfON_ME.cjs");
 const require_projection_sql = require("./projection-sql-DuCtFE9t.cjs");
 const require_view_compiler = require("./view-compiler-xiwm5iar.cjs");

package/core.d.cts

@@ -1,11 +1,11 @@
 import { A as relationshipsSchema, B as identityRefs, D as missingRequiredFields, E as filterSchema, F as ProjectionFieldBinding, I as ProjectionIdentity, L as ProjectionJoin, M as validateEntitiesConfig, N as BASE_REF, O as projectionFields, P as PROJECTION_KEY_PATTERN, R as ProjectionMapping, S as RelationshipsMap, T as entitiesConfigSchema, V as projectionSchema, _ as MATERIALIZING_CONCEPTS, a as ClivlyEntitiesConfig, b as RelationshipSpec, d as CrmConcept, g as FilterValue, h as FilterExpr, i as ClivlyConfigError, j as requiredFieldsFor, k as relationshipSchema, 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 defineClivlyConfig, x as RelationshipVia, y as REQUIRED_FIELDS, z as ProjectionRef } from "./entity-config-ApnT5j3X.cjs";
-import { A as UpdateCompanyInput, C as RecordSource, D as TaskFilters, E as TaskEntityType, F as isClosedStageType, M as UpdateDealInput, N as UpdateTaskInput, O as TaskPriority, P as ValueInterval, S as PipelineStageConfig, T as Task, _ as OPEN_STAGE_TYPE, a as Contact, b as PipelineConfig, c as CreateActivityInput, d as CreateDealInput, f as CreateTaskInput, g as Note, h as DealStage, i as CompanyFilters, j as UpdateContactInput, k as TaskStatus, l as CreateCompanyInput, m as Deal, n as ActivityType, o as ContactFilters, p as CrmRole, r as Company, s as ContactStatus, t as Activity, u as CreateContactInput, v as Page, w as StageType, x as PipelineKind, y as PageRequest } from "./types-B17TWEOL.cjs";
-import { a as authCustom, i as MembershipResolver, n as ClivlyUser, r as CrmMembership, t as ClivlyAuthAdapter } from "./auth-adapter-Csk9KkvI.cjs";
-import { t as CRMAdapter } from "./adapter-JpXSAnj-.cjs";
+import { A as UpdateCompanyInput, C as RecordSource, D as TaskFilters, E as TaskEntityType, F as isClosedStageType, M as UpdateDealInput, N as UpdateTaskInput, O as TaskPriority, P as ValueInterval, S as PipelineStageConfig, T as Task, _ as OPEN_STAGE_TYPE, a as Contact, b as PipelineConfig, c as CreateActivityInput, d as CreateDealInput, f as CreateTaskInput, g as Note, h as DealStage, i as CompanyFilters, j as UpdateContactInput, k as TaskStatus, l as CreateCompanyInput, m as Deal, n as ActivityType, o as ContactFilters, p as CrmRole, r as Company, s as ContactStatus, t as Activity, u as CreateContactInput, v as Page, w as StageType, x as PipelineKind, y as PageRequest } from "./types-CpAtAtxd.cjs";
+import { a as authCustom, i as MembershipResolver, n as ClivlyUser, r as CrmMembership, t as ClivlyAuthAdapter } from "./auth-adapter-Bt1GZiag.cjs";
+import { t as CRMAdapter } from "./adapter-IH3r_I8v.cjs";
 import { i as relationshipViaSignature, n as buildFilterFromDiscriminator, r as buildRelationships, t as RelationshipCandidate } from "./mapping-form-XsLLCqW_.cjs";
 import { i as mappingsToEntitiesConfig, t as EntityMappingRow } from "./mappings-config-iJzbcUMp.cjs";
 import { a as compileEntityView, i as ExplainResult, n as CompiledView, o as compileEntityViews, r as DEFAULT_VIEW_PREFIX, s as explainEntitiesConfig, t as CompileOptions } from "./view-compiler-Cq8apvZ4.cjs";
 import { c as SyncAction, f as isRemovalAction, g as runSync, h as resolveActions, l as SyncResult, m as reconcile, n as MirrorRecord, o as ResolvedMembership, r as PersistAction, s as SourceRow, t as EntitySyncResult, u as SyncStore } from "./sync-engine-CYsWOujz.cjs";
-import { A as PerSeatValueSource, C as HostOwnedCompanyField, D as isHostOwned, E as hostOwnedFieldMessage, O as rejectedCompanyFields, S as joinFansOut, T as SourcedRecord, _ as compileProjectionJoins, a as matchesCondition, b as quoteIdent, c as columnMetaFor, d as primaryKeyColumns, f as validateProjection, g as compileProjectionIdentity, h as compileProjectionFrom, i as evaluateStage, j as computeDealValue, k as rejectedContactFields, l as coversUniqueKey, m as PREVIEW_MAX_ROWS, n as ConditionOp, o as slugify, p as validateProjectionFilter, r as EvaluableRule, s as toObjectTypeSlug, t as Condition, u as hasRichMeta, v as compileProjectionPreview, w as HostOwnedContactField, x as fanOutJoins, y as compileProjectionSelect } from "./internal-vH5Rlg6Q.cjs";
+import { A as PerSeatValueSource, C as HostOwnedCompanyField, D as isHostOwned, E as hostOwnedFieldMessage, O as rejectedCompanyFields, S as joinFansOut, T as SourcedRecord, _ as compileProjectionJoins, a as matchesCondition, b as quoteIdent, c as columnMetaFor, d as primaryKeyColumns, f as validateProjection, g as compileProjectionIdentity, h as compileProjectionFrom, i as evaluateStage, j as computeDealValue, k as rejectedContactFields, l as coversUniqueKey, m as PREVIEW_MAX_ROWS, n as ConditionOp, o as slugify, p as validateProjectionFilter, r as EvaluableRule, s as toObjectTypeSlug, t as Condition, u as hasRichMeta, v as compileProjectionPreview, w as HostOwnedContactField, x as fanOutJoins, y as compileProjectionSelect } from "./internal-D2J4VQWT.cjs";
 import { a as IntegrationStep, c as StepProblem, i as IntegrationStatus, l as StepState, n as IntegrationFacts, o as NextAction, r as IntegrationState, s as StepId, t as ConnectionLiveness } from "./integration-state-BA4c0RbD.cjs";
 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 CompanyFilters, type CompileOptions, type CompiledView, type Condition, type ConditionOp, 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 EvaluableRule, type ExplainResult, type FilterExpr, type FilterValue, type HostOwnedCompanyField, type HostOwnedContactField, type IntegrationFacts, type IntegrationState, type IntegrationStatus, type IntegrationStep, MATERIALIZING_CONCEPTS, type MaterializingConcept, type MembershipResolver, type MirrorRecord, type NextAction, type Note, OPEN_STAGE_TYPE, PREVIEW_MAX_ROWS, PROJECTION_KEY_PATTERN, type Page, type PageRequest, type PerSeatValueSource, type PersistAction, type PipelineConfig, type PipelineKind, type PipelineStageConfig, type ProjectionFieldBinding, type ProjectionIdentity, type ProjectionJoin, type ProjectionMapping, type ProjectionRef, REQUIRED_FIELDS, type RecordSource, type RelationshipCandidate, type RelationshipSpec, type RelationshipVia, type RelationshipsMap, type ResolvedMembership, type SourceRow, type SourcedRecord, type StageType, type StepId, type StepProblem, type StepState, type SyncAction, type SyncResult, type SyncStore, type Task, type TaskEntityType, type TaskFilters, type TaskPriority, type TaskStatus, type UpdateCompanyInput, type UpdateContactInput, type UpdateDealInput, type UpdateTaskInput, type ValueInterval, authCustom, buildFilterFromDiscriminator, buildRelationships, columnMetaFor, compileEntityView, compileEntityViews, compileProjectionFrom, compileProjectionIdentity, compileProjectionJoins, compileProjectionPreview, compileProjectionSelect, computeDealValue, coversUniqueKey, defineClivlyConfig, entitiesConfigSchema, evaluateStage, explainEntitiesConfig, fanOutJoins, filterSchema, hasRichMeta, hostOwnedFieldMessage, identityRefs, isClosedStageType, isHostOwned, isRemovalAction, joinFansOut, mappingsToEntitiesConfig, matchesCondition, missingRequiredFields, primaryKeyColumns, projectionFields, projectionSchema, quoteIdent, reconcile, rejectedCompanyFields, rejectedContactFields, relationshipSchema, relationshipViaSignature, relationshipsSchema, requiredFieldsFor, resolveActions, runSync, slugify, toObjectTypeSlug, validateEntitiesConfig, validateProjection, validateProjectionFilter };

package/core.d.mts

@@ -1,11 +1,11 @@
 import { A as relationshipsSchema, B as identityRefs, D as missingRequiredFields, E as filterSchema, F as ProjectionFieldBinding, I as ProjectionIdentity, L as ProjectionJoin, M as validateEntitiesConfig, N as BASE_REF, O as projectionFields, P as PROJECTION_KEY_PATTERN, R as ProjectionMapping, S as RelationshipsMap, T as entitiesConfigSchema, V as projectionSchema, _ as MATERIALIZING_CONCEPTS, a as ClivlyEntitiesConfig, b as RelationshipSpec, d as CrmConcept, g as FilterValue, h as FilterExpr, i as ClivlyConfigError, j as requiredFieldsFor, k as relationshipSchema, 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 defineClivlyConfig, x as RelationshipVia, y as REQUIRED_FIELDS, z as ProjectionRef } from "./entity-config-CKcj4-M_.mjs";
-import { A as UpdateCompanyInput, C as RecordSource, D as TaskFilters, E as TaskEntityType, F as isClosedStageType, M as UpdateDealInput, N as UpdateTaskInput, O as TaskPriority, P as ValueInterval, S as PipelineStageConfig, T as Task, _ as OPEN_STAGE_TYPE, a as Contact, b as PipelineConfig, c as CreateActivityInput, d as CreateDealInput, f as CreateTaskInput, g as Note, h as DealStage, i as CompanyFilters, j as UpdateContactInput, k as TaskStatus, l as CreateCompanyInput, m as Deal, n as ActivityType, o as ContactFilters, p as CrmRole, r as Company, s as ContactStatus, t as Activity, u as CreateContactInput, v as Page, w as StageType, x as PipelineKind, y as PageRequest } from "./types-B17TWEOL.mjs";
-import { a as authCustom, i as MembershipResolver, n as ClivlyUser, r as CrmMembership, t as ClivlyAuthAdapter } from "./auth-adapter-C6rDx3XH.mjs";
-import { t as CRMAdapter } from "./adapter-B-iBMhl0.mjs";
+import { A as UpdateCompanyInput, C as RecordSource, D as TaskFilters, E as TaskEntityType, F as isClosedStageType, M as UpdateDealInput, N as UpdateTaskInput, O as TaskPriority, P as ValueInterval, S as PipelineStageConfig, T as Task, _ as OPEN_STAGE_TYPE, a as Contact, b as PipelineConfig, c as CreateActivityInput, d as CreateDealInput, f as CreateTaskInput, g as Note, h as DealStage, i as CompanyFilters, j as UpdateContactInput, k as TaskStatus, l as CreateCompanyInput, m as Deal, n as ActivityType, o as ContactFilters, p as CrmRole, r as Company, s as ContactStatus, t as Activity, u as CreateContactInput, v as Page, w as StageType, x as PipelineKind, y as PageRequest } from "./types-CpAtAtxd.mjs";
+import { a as authCustom, i as MembershipResolver, n as ClivlyUser, r as CrmMembership, t as ClivlyAuthAdapter } from "./auth-adapter-CHy273qb.mjs";
+import { t as CRMAdapter } from "./adapter-BMAUq4hf.mjs";
 import { i as relationshipViaSignature, n as buildFilterFromDiscriminator, r as buildRelationships, t as RelationshipCandidate } from "./mapping-form-Btn-7gzv.mjs";
 import { i as mappingsToEntitiesConfig, t as EntityMappingRow } from "./mappings-config-D6_oCi2Q.mjs";
 import { a as compileEntityView, i as ExplainResult, n as CompiledView, o as compileEntityViews, r as DEFAULT_VIEW_PREFIX, s as explainEntitiesConfig, t as CompileOptions } from "./view-compiler-CwKVoK1w.mjs";
 import { c as SyncAction, f as isRemovalAction, g as runSync, h as resolveActions, l as SyncResult, m as reconcile, n as MirrorRecord, o as ResolvedMembership, r as PersistAction, s as SourceRow, t as EntitySyncResult, u as SyncStore } from "./sync-engine-C_5TpvfX.mjs";
-import { A as PerSeatValueSource, C as HostOwnedCompanyField, D as isHostOwned, E as hostOwnedFieldMessage, O as rejectedCompanyFields, S as joinFansOut, T as SourcedRecord, _ as compileProjectionJoins, a as matchesCondition, b as quoteIdent, c as columnMetaFor, d as primaryKeyColumns, f as validateProjection, g as compileProjectionIdentity, h as compileProjectionFrom, i as evaluateStage, j as computeDealValue, k as rejectedContactFields, l as coversUniqueKey, m as PREVIEW_MAX_ROWS, n as ConditionOp, o as slugify, p as validateProjectionFilter, r as EvaluableRule, s as toObjectTypeSlug, t as Condition, u as hasRichMeta, v as compileProjectionPreview, w as HostOwnedContactField, x as fanOutJoins, y as compileProjectionSelect } from "./internal-Cmx7Zevf.mjs";
+import { A as PerSeatValueSource, C as HostOwnedCompanyField, D as isHostOwned, E as hostOwnedFieldMessage, O as rejectedCompanyFields, S as joinFansOut, T as SourcedRecord, _ as compileProjectionJoins, a as matchesCondition, b as quoteIdent, c as columnMetaFor, d as primaryKeyColumns, f as validateProjection, g as compileProjectionIdentity, h as compileProjectionFrom, i as evaluateStage, j as computeDealValue, k as rejectedContactFields, l as coversUniqueKey, m as PREVIEW_MAX_ROWS, n as ConditionOp, o as slugify, p as validateProjectionFilter, r as EvaluableRule, s as toObjectTypeSlug, t as Condition, u as hasRichMeta, v as compileProjectionPreview, w as HostOwnedContactField, x as fanOutJoins, y as compileProjectionSelect } from "./internal-C7NlPM3M.mjs";
 import { a as IntegrationStep, c as StepProblem, i as IntegrationStatus, l as StepState, n as IntegrationFacts, o as NextAction, r as IntegrationState, s as StepId, t as ConnectionLiveness } from "./integration-state-BA4c0RbD.mjs";
 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 CompanyFilters, type CompileOptions, type CompiledView, type Condition, type ConditionOp, 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 EvaluableRule, type ExplainResult, type FilterExpr, type FilterValue, type HostOwnedCompanyField, type HostOwnedContactField, type IntegrationFacts, type IntegrationState, type IntegrationStatus, type IntegrationStep, MATERIALIZING_CONCEPTS, type MaterializingConcept, type MembershipResolver, type MirrorRecord, type NextAction, type Note, OPEN_STAGE_TYPE, PREVIEW_MAX_ROWS, PROJECTION_KEY_PATTERN, type Page, type PageRequest, type PerSeatValueSource, type PersistAction, type PipelineConfig, type PipelineKind, type PipelineStageConfig, type ProjectionFieldBinding, type ProjectionIdentity, type ProjectionJoin, type ProjectionMapping, type ProjectionRef, REQUIRED_FIELDS, type RecordSource, type RelationshipCandidate, type RelationshipSpec, type RelationshipVia, type RelationshipsMap, type ResolvedMembership, type SourceRow, type SourcedRecord, type StageType, type StepId, type StepProblem, type StepState, type SyncAction, type SyncResult, type SyncStore, type Task, type TaskEntityType, type TaskFilters, type TaskPriority, type TaskStatus, type UpdateCompanyInput, type UpdateContactInput, type UpdateDealInput, type UpdateTaskInput, type ValueInterval, authCustom, buildFilterFromDiscriminator, buildRelationships, columnMetaFor, compileEntityView, compileEntityViews, compileProjectionFrom, compileProjectionIdentity, compileProjectionJoins, compileProjectionPreview, compileProjectionSelect, computeDealValue, coversUniqueKey, defineClivlyConfig, entitiesConfigSchema, evaluateStage, explainEntitiesConfig, fanOutJoins, filterSchema, hasRichMeta, hostOwnedFieldMessage, identityRefs, isClosedStageType, isHostOwned, isRemovalAction, joinFansOut, mappingsToEntitiesConfig, matchesCondition, missingRequiredFields, primaryKeyColumns, projectionFields, projectionSchema, quoteIdent, reconcile, rejectedCompanyFields, rejectedContactFields, relationshipSchema, relationshipViaSignature, relationshipsSchema, requiredFieldsFor, resolveActions, runSync, slugify, toObjectTypeSlug, validateEntitiesConfig, validateProjection, validateProjectionFilter };

package/core.mjs

@@ -2,7 +2,7 @@ import { i as projectionSchema, n as PROJECTION_KEY_PATTERN, r as identityRefs,
 import { C as hasRichMeta, S as coversUniqueKey, _ as validateProjection, a as MATERIALIZING_CONCEPTS, b as joinFansOut, c as defineClivlyConfig, d as missingRequiredFields, f as projectionFields, g as validateEntitiesConfig, h as requiredFieldsFor, i as ClivlyConfigError, l as entitiesConfigSchema, m as relationshipsSchema, n as CRM_CONCEPTS, o as REQUIRED_FIELDS, p as relationshipSchema, t as CANONICAL_FIELDS, u as filterSchema, v as validateProjectionFilter, w as primaryKeyColumns, x as columnMetaFor, y as fanOutJoins } from "./entity-config-Ccfb2IL9.mjs";
 import { n as mappingsToEntitiesConfig } from "./mappings-config-CwQNQ6bA.mjs";
 import { t as authCustom } from "./auth-adapter-gfVDxf3d.mjs";
-import { a as hostOwnedFieldMessage, c as rejectedContactFields, i as toObjectTypeSlug, l as computeDealValue, n as matchesCondition, o as isHostOwned, r as slugify, s as rejectedCompanyFields, t as evaluateStage } from "./internal-u0Bks5Gr.mjs";
+import { a as hostOwnedFieldMessage, c as rejectedContactFields, i as toObjectTypeSlug, l as computeDealValue, n as matchesCondition, o as isHostOwned, r as slugify, s as rejectedCompanyFields, t as evaluateStage } from "./internal-CLvZdVj5.mjs";
 import { n as buildRelationships, r as relationshipViaSignature, t as buildFilterFromDiscriminator } from "./mapping-form-DigkuvFc.mjs";
 import { a as compileProjectionPreview, i as compileProjectionJoins, n as compileProjectionFrom, o as compileProjectionSelect, r as compileProjectionIdentity, s as quoteIdent, t as PREVIEW_MAX_ROWS } from "./projection-sql-DweUaWRc.mjs";
 import { i as explainEntitiesConfig, n as compileEntityView, r as compileEntityViews, t as DEFAULT_VIEW_PREFIX } from "./view-compiler-C-6RydKK.mjs";

package/{internal-Cmx7Zevf.d.mts → internal-C7NlPM3M.d.mts}

@@ -9,7 +9,7 @@ import { L as ProjectionJoin, R as ProjectionMapping, h as FilterExpr, l as Conf
  * D8 made for stage-rule conditions.
  */
 interface PerSeatValueSource {
-  /** Flat monthly fee in cents, added before the interval is normalised. */
+  /** Flat fee in cents, using the same price basis as the plan prices. */
   baseFeeCents?: number;
   /** Mapped column holding "month" or "year". Absent means always monthly. */
   intervalField?: string;
@@ -18,6 +18,8 @@ interface PerSeatValueSource {
   planField: string;
   /** Unit price in cents, keyed by the value found in `planField`. */
   plans: Record<string, number>;
+  /** Monthly rates or amounts charged each billing period. Omitted preserves legacy behaviour. */
+  priceBasis?: "monthly" | "billing_interval";
   /** Mapped column holding the seat count. */
   seatField: string;
   /** Stage types whose deals are worth nothing (usually `["lost"]`). */

package/{internal-u0Bks5Gr.mjs → internal-CLvZdVj5.mjs}

@@ -23,6 +23,18 @@ function computeDealValue(source, fields, mappedFields, stageType) {
 	const seats = Number(rawSeats);
 	if (!Number.isSafeInteger(seats)) return null;
 	const monthly = (source.baseFeeCents ?? 0) + seats * unitPriceCents;
+	if (!Number.isSafeInteger(monthly) || monthly < 0) return null;
+	return normalizePrice(monthly, source, fields, mappedFields);
+}
+/** Preserve old configurations while making new price bases explicit. */
+function normalizePrice(monthly, source, fields, mappedFields) {
+	if (source.priceBasis === "monthly") return monthly;
+	if (source.priceBasis === "billing_interval") {
+		const interval = source.intervalField && mappedFields.has(source.intervalField) ? fields[source.intervalField]?.trim().toLowerCase() : null;
+		if (interval === "month" || interval === "monthly") return monthly;
+		if (interval === "year" || interval === "annual" || interval === "annually" || interval === "yearly") return Math.round(monthly / MONTHS_PER_YEAR);
+		return null;
+	}
 	return source.intervalField !== void 0 && mappedFields.has(source.intervalField) && fields[source.intervalField] === "year" ? Math.round(monthly / MONTHS_PER_YEAR) : monthly;
 }
 //#endregion

package/{internal-vH5Rlg6Q.d.cts → internal-D2J4VQWT.d.cts}

@@ -9,7 +9,7 @@ import { L as ProjectionJoin, R as ProjectionMapping, h as FilterExpr, l as Conf
  * D8 made for stage-rule conditions.
  */
 interface PerSeatValueSource {
-  /** Flat monthly fee in cents, added before the interval is normalised. */
+  /** Flat fee in cents, using the same price basis as the plan prices. */
   baseFeeCents?: number;
   /** Mapped column holding "month" or "year". Absent means always monthly. */
   intervalField?: string;
@@ -18,6 +18,8 @@ interface PerSeatValueSource {
   planField: string;
   /** Unit price in cents, keyed by the value found in `planField`. */
   plans: Record<string, number>;
+  /** Monthly rates or amounts charged each billing period. Omitted preserves legacy behaviour. */
+  priceBasis?: "monthly" | "billing_interval";
   /** Mapped column holding the seat count. */
   seatField: string;
   /** Stage types whose deals are worth nothing (usually `["lost"]`). */

package/{internal-BxtvxF7Z.cjs → internal-DsArcqkP.cjs}

@@ -23,6 +23,18 @@ function computeDealValue(source, fields, mappedFields, stageType) {
 	const seats = Number(rawSeats);
 	if (!Number.isSafeInteger(seats)) return null;
 	const monthly = (source.baseFeeCents ?? 0) + seats * unitPriceCents;
+	if (!Number.isSafeInteger(monthly) || monthly < 0) return null;
+	return normalizePrice(monthly, source, fields, mappedFields);
+}
+/** Preserve old configurations while making new price bases explicit. */
+function normalizePrice(monthly, source, fields, mappedFields) {
+	if (source.priceBasis === "monthly") return monthly;
+	if (source.priceBasis === "billing_interval") {
+		const interval = source.intervalField && mappedFields.has(source.intervalField) ? fields[source.intervalField]?.trim().toLowerCase() : null;
+		if (interval === "month" || interval === "monthly") return monthly;
+		if (interval === "year" || interval === "annual" || interval === "annually" || interval === "yearly") return Math.round(monthly / MONTHS_PER_YEAR);
+		return null;
+	}
 	return source.intervalField !== void 0 && mappedFields.has(source.intervalField) && fields[source.intervalField] === "year" ? Math.round(monthly / MONTHS_PER_YEAR) : monthly;
 }
 //#endregion

package/internal-adapter.d.cts

@@ -1,2 +1,2 @@
-import { t as CRMAdapter } from "./adapter-JpXSAnj-.cjs";
+import { t as CRMAdapter } from "./adapter-IH3r_I8v.cjs";
 export { CRMAdapter };

package/internal-adapter.d.mts

@@ -1,2 +1,2 @@
-import { t as CRMAdapter } from "./adapter-B-iBMhl0.mjs";
+import { t as CRMAdapter } from "./adapter-BMAUq4hf.mjs";
 export { CRMAdapter };

package/internal-auth-adapter.d.cts

@@ -1,2 +1,2 @@
-import { a as authCustom, i as MembershipResolver, n as ClivlyUser, r as CrmMembership, t as ClivlyAuthAdapter } from "./auth-adapter-Csk9KkvI.cjs";
+import { a as authCustom, i as MembershipResolver, n as ClivlyUser, r as CrmMembership, t as ClivlyAuthAdapter } from "./auth-adapter-Bt1GZiag.cjs";
 export { ClivlyAuthAdapter, ClivlyUser, CrmMembership, MembershipResolver, authCustom };

package/internal-auth-adapter.d.mts

@@ -1,2 +1,2 @@
-import { a as authCustom, i as MembershipResolver, n as ClivlyUser, r as CrmMembership, t as ClivlyAuthAdapter } from "./auth-adapter-C6rDx3XH.mjs";
+import { a as authCustom, i as MembershipResolver, n as ClivlyUser, r as CrmMembership, t as ClivlyAuthAdapter } from "./auth-adapter-CHy273qb.mjs";
 export { ClivlyAuthAdapter, ClivlyUser, CrmMembership, MembershipResolver, authCustom };

package/internal-types.d.cts

@@ -1,2 +1,2 @@
-import { A as UpdateCompanyInput, C as RecordSource, D as TaskFilters, E as TaskEntityType, F as isClosedStageType, M as UpdateDealInput, N as UpdateTaskInput, O as TaskPriority, P as ValueInterval, S as PipelineStageConfig, T as Task, _ as OPEN_STAGE_TYPE, a as Contact, b as PipelineConfig, c as CreateActivityInput, d as CreateDealInput, f as CreateTaskInput, g as Note, h as DealStage, i as CompanyFilters, j as UpdateContactInput, k as TaskStatus, l as CreateCompanyInput, m as Deal, n as ActivityType, o as ContactFilters, p as CrmRole, r as Company, s as ContactStatus, t as Activity, u as CreateContactInput, v as Page, w as StageType, x as PipelineKind, y as PageRequest } from "./types-B17TWEOL.cjs";
+import { A as UpdateCompanyInput, C as RecordSource, D as TaskFilters, E as TaskEntityType, F as isClosedStageType, M as UpdateDealInput, N as UpdateTaskInput, O as TaskPriority, P as ValueInterval, S as PipelineStageConfig, T as Task, _ as OPEN_STAGE_TYPE, a as Contact, b as PipelineConfig, c as CreateActivityInput, d as CreateDealInput, f as CreateTaskInput, g as Note, h as DealStage, i as CompanyFilters, j as UpdateContactInput, k as TaskStatus, l as CreateCompanyInput, m as Deal, n as ActivityType, o as ContactFilters, p as CrmRole, r as Company, s as ContactStatus, t as Activity, u as CreateContactInput, v as Page, w as StageType, x as PipelineKind, y as PageRequest } from "./types-CpAtAtxd.cjs";
 export { Activity, ActivityType, Company, CompanyFilters, Contact, ContactFilters, ContactStatus, CreateActivityInput, CreateCompanyInput, CreateContactInput, CreateDealInput, CreateTaskInput, CrmRole, Deal, DealStage, Note, OPEN_STAGE_TYPE, Page, PageRequest, PipelineConfig, PipelineKind, PipelineStageConfig, RecordSource, StageType, Task, TaskEntityType, TaskFilters, TaskPriority, TaskStatus, UpdateCompanyInput, UpdateContactInput, UpdateDealInput, UpdateTaskInput, ValueInterval, isClosedStageType };

package/internal-types.d.mts

@@ -1,2 +1,2 @@
-import { A as UpdateCompanyInput, C as RecordSource, D as TaskFilters, E as TaskEntityType, F as isClosedStageType, M as UpdateDealInput, N as UpdateTaskInput, O as TaskPriority, P as ValueInterval, S as PipelineStageConfig, T as Task, _ as OPEN_STAGE_TYPE, a as Contact, b as PipelineConfig, c as CreateActivityInput, d as CreateDealInput, f as CreateTaskInput, g as Note, h as DealStage, i as CompanyFilters, j as UpdateContactInput, k as TaskStatus, l as CreateCompanyInput, m as Deal, n as ActivityType, o as ContactFilters, p as CrmRole, r as Company, s as ContactStatus, t as Activity, u as CreateContactInput, v as Page, w as StageType, x as PipelineKind, y as PageRequest } from "./types-B17TWEOL.mjs";
+import { A as UpdateCompanyInput, C as RecordSource, D as TaskFilters, E as TaskEntityType, F as isClosedStageType, M as UpdateDealInput, N as UpdateTaskInput, O as TaskPriority, P as ValueInterval, S as PipelineStageConfig, T as Task, _ as OPEN_STAGE_TYPE, a as Contact, b as PipelineConfig, c as CreateActivityInput, d as CreateDealInput, f as CreateTaskInput, g as Note, h as DealStage, i as CompanyFilters, j as UpdateContactInput, k as TaskStatus, l as CreateCompanyInput, m as Deal, n as ActivityType, o as ContactFilters, p as CrmRole, r as Company, s as ContactStatus, t as Activity, u as CreateContactInput, v as Page, w as StageType, x as PipelineKind, y as PageRequest } from "./types-CpAtAtxd.mjs";
 export { Activity, ActivityType, Company, CompanyFilters, Contact, ContactFilters, ContactStatus, CreateActivityInput, CreateCompanyInput, CreateContactInput, CreateDealInput, CreateTaskInput, CrmRole, Deal, DealStage, Note, OPEN_STAGE_TYPE, Page, PageRequest, PipelineConfig, PipelineKind, PipelineStageConfig, RecordSource, StageType, Task, TaskEntityType, TaskFilters, TaskPriority, TaskStatus, UpdateCompanyInput, UpdateContactInput, UpdateDealInput, UpdateTaskInput, ValueInterval, isClosedStageType };

package/internal.cjs

@@ -3,7 +3,7 @@ const require_projection = require("./projection-BELgANG2.cjs");
 const require_entity_config = require("./entity-config-BI4RYNKL.cjs");
 const require_mappings_config = require("./mappings-config-BCsRLohT.cjs");
 const require_auth_adapter = require("./auth-adapter-CiEXcweZ.cjs");
-const require_internal = require("./internal-BxtvxF7Z.cjs");
+const require_internal = require("./internal-DsArcqkP.cjs");
 const require_mapping_form = require("./mapping-form-BpfON_ME.cjs");
 const require_projection_sql = require("./projection-sql-DuCtFE9t.cjs");
 const require_view_compiler = require("./view-compiler-xiwm5iar.cjs");

package/internal.d.cts

@@ -1,11 +1,11 @@
 import { A as relationshipsSchema, B as identityRefs, D as missingRequiredFields, E as filterSchema, F as ProjectionFieldBinding, I as ProjectionIdentity, L as ProjectionJoin, M as validateEntitiesConfig, N as BASE_REF, O as projectionFields, P as PROJECTION_KEY_PATTERN, R as ProjectionMapping, S as RelationshipsMap, T as entitiesConfigSchema, V as projectionSchema, _ as MATERIALIZING_CONCEPTS, a as ClivlyEntitiesConfig, b as RelationshipSpec, d as CrmConcept, g as FilterValue, h as FilterExpr, i as ClivlyConfigError, j as requiredFieldsFor, k as relationshipSchema, 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 defineClivlyConfig, x as RelationshipVia, y as REQUIRED_FIELDS, z as ProjectionRef } from "./entity-config-ApnT5j3X.cjs";
-import { A as UpdateCompanyInput, C as RecordSource, D as TaskFilters, E as TaskEntityType, F as isClosedStageType, M as UpdateDealInput, N as UpdateTaskInput, O as TaskPriority, P as ValueInterval, S as PipelineStageConfig, T as Task, _ as OPEN_STAGE_TYPE, a as Contact, b as PipelineConfig, c as CreateActivityInput, d as CreateDealInput, f as CreateTaskInput, g as Note, h as DealStage, i as CompanyFilters, j as UpdateContactInput, k as TaskStatus, l as CreateCompanyInput, m as Deal, n as ActivityType, o as ContactFilters, p as CrmRole, r as Company, s as ContactStatus, t as Activity, u as CreateContactInput, v as Page, w as StageType, x as PipelineKind, y as PageRequest } from "./types-B17TWEOL.cjs";
-import { a as authCustom, i as MembershipResolver, n as ClivlyUser, r as CrmMembership, t as ClivlyAuthAdapter } from "./auth-adapter-Csk9KkvI.cjs";
-import { t as CRMAdapter } from "./adapter-JpXSAnj-.cjs";
+import { A as UpdateCompanyInput, C as RecordSource, D as TaskFilters, E as TaskEntityType, F as isClosedStageType, M as UpdateDealInput, N as UpdateTaskInput, O as TaskPriority, P as ValueInterval, S as PipelineStageConfig, T as Task, _ as OPEN_STAGE_TYPE, a as Contact, b as PipelineConfig, c as CreateActivityInput, d as CreateDealInput, f as CreateTaskInput, g as Note, h as DealStage, i as CompanyFilters, j as UpdateContactInput, k as TaskStatus, l as CreateCompanyInput, m as Deal, n as ActivityType, o as ContactFilters, p as CrmRole, r as Company, s as ContactStatus, t as Activity, u as CreateContactInput, v as Page, w as StageType, x as PipelineKind, y as PageRequest } from "./types-CpAtAtxd.cjs";
+import { a as authCustom, i as MembershipResolver, n as ClivlyUser, r as CrmMembership, t as ClivlyAuthAdapter } from "./auth-adapter-Bt1GZiag.cjs";
+import { t as CRMAdapter } from "./adapter-IH3r_I8v.cjs";
 import { i as relationshipViaSignature, n as buildFilterFromDiscriminator, r as buildRelationships, t as RelationshipCandidate } from "./mapping-form-XsLLCqW_.cjs";
 import { i as mappingsToEntitiesConfig, t as EntityMappingRow } from "./mappings-config-iJzbcUMp.cjs";
 import { a as compileEntityView, i as ExplainResult, n as CompiledView, o as compileEntityViews, r as DEFAULT_VIEW_PREFIX, s as explainEntitiesConfig, t as CompileOptions } from "./view-compiler-Cq8apvZ4.cjs";
 import { c as SyncAction, f as isRemovalAction, g as runSync, h as resolveActions, l as SyncResult, m as reconcile, n as MirrorRecord, o as ResolvedMembership, r as PersistAction, s as SourceRow, t as EntitySyncResult, u as SyncStore } from "./sync-engine-CYsWOujz.cjs";
-import { A as PerSeatValueSource, C as HostOwnedCompanyField, D as isHostOwned, E as hostOwnedFieldMessage, O as rejectedCompanyFields, S as joinFansOut, T as SourcedRecord, _ as compileProjectionJoins, a as matchesCondition, b as quoteIdent, c as columnMetaFor, d as primaryKeyColumns, f as validateProjection, g as compileProjectionIdentity, h as compileProjectionFrom, i as evaluateStage, j as computeDealValue, k as rejectedContactFields, l as coversUniqueKey, m as PREVIEW_MAX_ROWS, n as ConditionOp, o as slugify, p as validateProjectionFilter, r as EvaluableRule, s as toObjectTypeSlug, t as Condition, u as hasRichMeta, v as compileProjectionPreview, w as HostOwnedContactField, x as fanOutJoins, y as compileProjectionSelect } from "./internal-vH5Rlg6Q.cjs";
+import { A as PerSeatValueSource, C as HostOwnedCompanyField, D as isHostOwned, E as hostOwnedFieldMessage, O as rejectedCompanyFields, S as joinFansOut, T as SourcedRecord, _ as compileProjectionJoins, a as matchesCondition, b as quoteIdent, c as columnMetaFor, d as primaryKeyColumns, f as validateProjection, g as compileProjectionIdentity, h as compileProjectionFrom, i as evaluateStage, j as computeDealValue, k as rejectedContactFields, l as coversUniqueKey, m as PREVIEW_MAX_ROWS, n as ConditionOp, o as slugify, p as validateProjectionFilter, r as EvaluableRule, s as toObjectTypeSlug, t as Condition, u as hasRichMeta, v as compileProjectionPreview, w as HostOwnedContactField, x as fanOutJoins, y as compileProjectionSelect } from "./internal-D2J4VQWT.cjs";
 import { a as IntegrationStep, c as StepProblem, i as IntegrationStatus, l as StepState, n as IntegrationFacts, o as NextAction, r as IntegrationState, s as StepId, t as ConnectionLiveness } from "./integration-state-BA4c0RbD.cjs";
 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 CompanyFilters, type CompileOptions, type CompiledView, type Condition, type ConditionOp, 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 EvaluableRule, type ExplainResult, type FilterExpr, type FilterValue, type HostOwnedCompanyField, type HostOwnedContactField, type IntegrationFacts, type IntegrationState, type IntegrationStatus, type IntegrationStep, MATERIALIZING_CONCEPTS, type MaterializingConcept, type MembershipResolver, type MirrorRecord, type NextAction, type Note, OPEN_STAGE_TYPE, PREVIEW_MAX_ROWS, PROJECTION_KEY_PATTERN, type Page, type PageRequest, type PerSeatValueSource, type PersistAction, type PipelineConfig, type PipelineKind, type PipelineStageConfig, type ProjectionFieldBinding, type ProjectionIdentity, type ProjectionJoin, type ProjectionMapping, type ProjectionRef, REQUIRED_FIELDS, type RecordSource, type RelationshipCandidate, type RelationshipSpec, type RelationshipVia, type RelationshipsMap, type ResolvedMembership, type SourceRow, type SourcedRecord, type StageType, type StepId, type StepProblem, type StepState, type SyncAction, type SyncResult, type SyncStore, type Task, type TaskEntityType, type TaskFilters, type TaskPriority, type TaskStatus, type UpdateCompanyInput, type UpdateContactInput, type UpdateDealInput, type UpdateTaskInput, type ValueInterval, authCustom, buildFilterFromDiscriminator, buildRelationships, columnMetaFor, compileEntityView, compileEntityViews, compileProjectionFrom, compileProjectionIdentity, compileProjectionJoins, compileProjectionPreview, compileProjectionSelect, computeDealValue, coversUniqueKey, defineClivlyConfig, entitiesConfigSchema, evaluateStage, explainEntitiesConfig, fanOutJoins, filterSchema, hasRichMeta, hostOwnedFieldMessage, identityRefs, isClosedStageType, isHostOwned, isRemovalAction, joinFansOut, mappingsToEntitiesConfig, matchesCondition, missingRequiredFields, primaryKeyColumns, projectionFields, projectionSchema, quoteIdent, reconcile, rejectedCompanyFields, rejectedContactFields, relationshipSchema, relationshipViaSignature, relationshipsSchema, requiredFieldsFor, resolveActions, runSync, slugify, toObjectTypeSlug, validateEntitiesConfig, validateProjection, validateProjectionFilter };

package/internal.d.mts

@@ -1,11 +1,11 @@
 import { A as relationshipsSchema, B as identityRefs, D as missingRequiredFields, E as filterSchema, F as ProjectionFieldBinding, I as ProjectionIdentity, L as ProjectionJoin, M as validateEntitiesConfig, N as BASE_REF, O as projectionFields, P as PROJECTION_KEY_PATTERN, R as ProjectionMapping, S as RelationshipsMap, T as entitiesConfigSchema, V as projectionSchema, _ as MATERIALIZING_CONCEPTS, a as ClivlyEntitiesConfig, b as RelationshipSpec, d as CrmConcept, g as FilterValue, h as FilterExpr, i as ClivlyConfigError, j as requiredFieldsFor, k as relationshipSchema, 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 defineClivlyConfig, x as RelationshipVia, y as REQUIRED_FIELDS, z as ProjectionRef } from "./entity-config-CKcj4-M_.mjs";
-import { A as UpdateCompanyInput, C as RecordSource, D as TaskFilters, E as TaskEntityType, F as isClosedStageType, M as UpdateDealInput, N as UpdateTaskInput, O as TaskPriority, P as ValueInterval, S as PipelineStageConfig, T as Task, _ as OPEN_STAGE_TYPE, a as Contact, b as PipelineConfig, c as CreateActivityInput, d as CreateDealInput, f as CreateTaskInput, g as Note, h as DealStage, i as CompanyFilters, j as UpdateContactInput, k as TaskStatus, l as CreateCompanyInput, m as Deal, n as ActivityType, o as ContactFilters, p as CrmRole, r as Company, s as ContactStatus, t as Activity, u as CreateContactInput, v as Page, w as StageType, x as PipelineKind, y as PageRequest } from "./types-B17TWEOL.mjs";
-import { a as authCustom, i as MembershipResolver, n as ClivlyUser, r as CrmMembership, t as ClivlyAuthAdapter } from "./auth-adapter-C6rDx3XH.mjs";
-import { t as CRMAdapter } from "./adapter-B-iBMhl0.mjs";
+import { A as UpdateCompanyInput, C as RecordSource, D as TaskFilters, E as TaskEntityType, F as isClosedStageType, M as UpdateDealInput, N as UpdateTaskInput, O as TaskPriority, P as ValueInterval, S as PipelineStageConfig, T as Task, _ as OPEN_STAGE_TYPE, a as Contact, b as PipelineConfig, c as CreateActivityInput, d as CreateDealInput, f as CreateTaskInput, g as Note, h as DealStage, i as CompanyFilters, j as UpdateContactInput, k as TaskStatus, l as CreateCompanyInput, m as Deal, n as ActivityType, o as ContactFilters, p as CrmRole, r as Company, s as ContactStatus, t as Activity, u as CreateContactInput, v as Page, w as StageType, x as PipelineKind, y as PageRequest } from "./types-CpAtAtxd.mjs";
+import { a as authCustom, i as MembershipResolver, n as ClivlyUser, r as CrmMembership, t as ClivlyAuthAdapter } from "./auth-adapter-CHy273qb.mjs";
+import { t as CRMAdapter } from "./adapter-BMAUq4hf.mjs";
 import { i as relationshipViaSignature, n as buildFilterFromDiscriminator, r as buildRelationships, t as RelationshipCandidate } from "./mapping-form-Btn-7gzv.mjs";
 import { i as mappingsToEntitiesConfig, t as EntityMappingRow } from "./mappings-config-D6_oCi2Q.mjs";
 import { a as compileEntityView, i as ExplainResult, n as CompiledView, o as compileEntityViews, r as DEFAULT_VIEW_PREFIX, s as explainEntitiesConfig, t as CompileOptions } from "./view-compiler-CwKVoK1w.mjs";
 import { c as SyncAction, f as isRemovalAction, g as runSync, h as resolveActions, l as SyncResult, m as reconcile, n as MirrorRecord, o as ResolvedMembership, r as PersistAction, s as SourceRow, t as EntitySyncResult, u as SyncStore } from "./sync-engine-C_5TpvfX.mjs";
-import { A as PerSeatValueSource, C as HostOwnedCompanyField, D as isHostOwned, E as hostOwnedFieldMessage, O as rejectedCompanyFields, S as joinFansOut, T as SourcedRecord, _ as compileProjectionJoins, a as matchesCondition, b as quoteIdent, c as columnMetaFor, d as primaryKeyColumns, f as validateProjection, g as compileProjectionIdentity, h as compileProjectionFrom, i as evaluateStage, j as computeDealValue, k as rejectedContactFields, l as coversUniqueKey, m as PREVIEW_MAX_ROWS, n as ConditionOp, o as slugify, p as validateProjectionFilter, r as EvaluableRule, s as toObjectTypeSlug, t as Condition, u as hasRichMeta, v as compileProjectionPreview, w as HostOwnedContactField, x as fanOutJoins, y as compileProjectionSelect } from "./internal-Cmx7Zevf.mjs";
+import { A as PerSeatValueSource, C as HostOwnedCompanyField, D as isHostOwned, E as hostOwnedFieldMessage, O as rejectedCompanyFields, S as joinFansOut, T as SourcedRecord, _ as compileProjectionJoins, a as matchesCondition, b as quoteIdent, c as columnMetaFor, d as primaryKeyColumns, f as validateProjection, g as compileProjectionIdentity, h as compileProjectionFrom, i as evaluateStage, j as computeDealValue, k as rejectedContactFields, l as coversUniqueKey, m as PREVIEW_MAX_ROWS, n as ConditionOp, o as slugify, p as validateProjectionFilter, r as EvaluableRule, s as toObjectTypeSlug, t as Condition, u as hasRichMeta, v as compileProjectionPreview, w as HostOwnedContactField, x as fanOutJoins, y as compileProjectionSelect } from "./internal-C7NlPM3M.mjs";
 import { a as IntegrationStep, c as StepProblem, i as IntegrationStatus, l as StepState, n as IntegrationFacts, o as NextAction, r as IntegrationState, s as StepId, t as ConnectionLiveness } from "./integration-state-BA4c0RbD.mjs";
 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 CompanyFilters, type CompileOptions, type CompiledView, type Condition, type ConditionOp, 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 EvaluableRule, type ExplainResult, type FilterExpr, type FilterValue, type HostOwnedCompanyField, type HostOwnedContactField, type IntegrationFacts, type IntegrationState, type IntegrationStatus, type IntegrationStep, MATERIALIZING_CONCEPTS, type MaterializingConcept, type MembershipResolver, type MirrorRecord, type NextAction, type Note, OPEN_STAGE_TYPE, PREVIEW_MAX_ROWS, PROJECTION_KEY_PATTERN, type Page, type PageRequest, type PerSeatValueSource, type PersistAction, type PipelineConfig, type PipelineKind, type PipelineStageConfig, type ProjectionFieldBinding, type ProjectionIdentity, type ProjectionJoin, type ProjectionMapping, type ProjectionRef, REQUIRED_FIELDS, type RecordSource, type RelationshipCandidate, type RelationshipSpec, type RelationshipVia, type RelationshipsMap, type ResolvedMembership, type SourceRow, type SourcedRecord, type StageType, type StepId, type StepProblem, type StepState, type SyncAction, type SyncResult, type SyncStore, type Task, type TaskEntityType, type TaskFilters, type TaskPriority, type TaskStatus, type UpdateCompanyInput, type UpdateContactInput, type UpdateDealInput, type UpdateTaskInput, type ValueInterval, authCustom, buildFilterFromDiscriminator, buildRelationships, columnMetaFor, compileEntityView, compileEntityViews, compileProjectionFrom, compileProjectionIdentity, compileProjectionJoins, compileProjectionPreview, compileProjectionSelect, computeDealValue, coversUniqueKey, defineClivlyConfig, entitiesConfigSchema, evaluateStage, explainEntitiesConfig, fanOutJoins, filterSchema, hasRichMeta, hostOwnedFieldMessage, identityRefs, isClosedStageType, isHostOwned, isRemovalAction, joinFansOut, mappingsToEntitiesConfig, matchesCondition, missingRequiredFields, primaryKeyColumns, projectionFields, projectionSchema, quoteIdent, reconcile, rejectedCompanyFields, rejectedContactFields, relationshipSchema, relationshipViaSignature, relationshipsSchema, requiredFieldsFor, resolveActions, runSync, slugify, toObjectTypeSlug, validateEntitiesConfig, validateProjection, validateProjectionFilter };

package/internal.mjs

@@ -2,7 +2,7 @@ import { i as projectionSchema, n as PROJECTION_KEY_PATTERN, r as identityRefs,
 import { C as hasRichMeta, S as coversUniqueKey, _ as validateProjection, a as MATERIALIZING_CONCEPTS, b as joinFansOut, c as defineClivlyConfig, d as missingRequiredFields, f as projectionFields, g as validateEntitiesConfig, h as requiredFieldsFor, i as ClivlyConfigError, l as entitiesConfigSchema, m as relationshipsSchema, n as CRM_CONCEPTS, o as REQUIRED_FIELDS, p as relationshipSchema, t as CANONICAL_FIELDS, u as filterSchema, v as validateProjectionFilter, w as primaryKeyColumns, x as columnMetaFor, y as fanOutJoins } from "./entity-config-Ccfb2IL9.mjs";
 import { n as mappingsToEntitiesConfig } from "./mappings-config-CwQNQ6bA.mjs";
 import { t as authCustom } from "./auth-adapter-gfVDxf3d.mjs";
-import { a as hostOwnedFieldMessage, c as rejectedContactFields, i as toObjectTypeSlug, l as computeDealValue, n as matchesCondition, o as isHostOwned, r as slugify, s as rejectedCompanyFields, t as evaluateStage } from "./internal-u0Bks5Gr.mjs";
+import { a as hostOwnedFieldMessage, c as rejectedContactFields, i as toObjectTypeSlug, l as computeDealValue, n as matchesCondition, o as isHostOwned, r as slugify, s as rejectedCompanyFields, t as evaluateStage } from "./internal-CLvZdVj5.mjs";
 import { n as buildRelationships, r as relationshipViaSignature, t as buildFilterFromDiscriminator } from "./mapping-form-DigkuvFc.mjs";
 import { a as compileProjectionPreview, i as compileProjectionJoins, n as compileProjectionFrom, o as compileProjectionSelect, r as compileProjectionIdentity, s as quoteIdent, t as PREVIEW_MAX_ROWS } from "./projection-sql-DweUaWRc.mjs";
 import { i as explainEntitiesConfig, n as compileEntityView, r as compileEntityViews, t as DEFAULT_VIEW_PREFIX } from "./view-compiler-C-6RydKK.mjs";

package/package.json

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

package/{types-B17TWEOL.d.cts → types-CpAtAtxd.d.cts}

@@ -84,12 +84,21 @@ interface Company {
 }
 interface Deal {
   closeDate: Date | null;
+  /** The organisation this deal belongs to, when one is linked. */
+  companyId: string | null;
   contactId: string | null;
   createdAt: Date;
   id: string;
   name: string;
   orgId: string;
   owner: string | null;
+  /**
+   * The board this deal belongs to. NULL means the org's default pipeline: the
+   * sync mirror wrote deals before pipelines existed, and a deal created with
+   * no pipeline lands on the default. Stage keys are unique per pipeline, so
+   * a board must filter on this, never on stage key alone.
+   */
+  pipelineId: string | null;
   position: number | null;
   stage: DealStage;
   /**
@@ -116,6 +125,11 @@ interface Task {
   createdAt: Date;
   createdBy: string | null;
   description: string | null;
+  /**
+   * Whether `dueAt` is a calendar date (stored as midnight UTC) rather than a
+   * moment. Absent or null: a midnight-UTC `dueAt` is read as a date.
+   */
+  dueAllDay?: boolean | null;
   dueAt: Date | null;
   entityId: string | null;
   entityType: TaskEntityType | null;
@@ -203,6 +217,11 @@ interface CreateTaskInput {
   assignee?: string;
   createdBy?: string;
   description?: string;
+  /**
+   * Whether `dueAt` is a calendar date (stored as midnight UTC) rather than a
+   * moment. Absent or null: a midnight-UTC `dueAt` is read as a date.
+   */
+  dueAllDay?: boolean | null;
   dueAt?: Date;
   entityId?: string;
   entityType?: TaskEntityType;
@@ -212,6 +231,11 @@ interface CreateTaskInput {
 interface UpdateTaskInput {
   assignee?: string | null;
   description?: string | null;
+  /**
+   * Whether `dueAt` is a calendar date (stored as midnight UTC) rather than a
+   * moment. Absent or null: a midnight-UTC `dueAt` is read as a date.
+   */
+  dueAllDay?: boolean | null;
   dueAt?: Date | null;
   entityId?: string | null;
   entityType?: TaskEntityType | null;
@@ -244,6 +268,17 @@ interface ContactFilters {
    * row is no longer sync-provenanced.
    */
   excludeArchived?: boolean;
+  /**
+   * Case-insensitive substring match on name or email.
+   *
+   * Applied in SQL, not over an already-fetched page: a filter applied after
+   * paging returns a partial page and a cursor that skips the rows it dropped,
+   * so "page 2" of a search is not the second page of the matches. An empty or
+   * whitespace-only value is ignored rather than matching nothing.
+   *
+   * LIKE metacharacters in the term are escaped and matched literally — a
+   * search for `%` finds contacts containing a percent sign, not every row.
+   */
   search?: string;
   source?: RecordSource;
   status?: ContactStatus;

package/{types-B17TWEOL.d.mts → types-CpAtAtxd.d.mts}

@@ -84,12 +84,21 @@ interface Company {
 }
 interface Deal {
   closeDate: Date | null;
+  /** The organisation this deal belongs to, when one is linked. */
+  companyId: string | null;
   contactId: string | null;
   createdAt: Date;
   id: string;
   name: string;
   orgId: string;
   owner: string | null;
+  /**
+   * The board this deal belongs to. NULL means the org's default pipeline: the
+   * sync mirror wrote deals before pipelines existed, and a deal created with
+   * no pipeline lands on the default. Stage keys are unique per pipeline, so
+   * a board must filter on this, never on stage key alone.
+   */
+  pipelineId: string | null;
   position: number | null;
   stage: DealStage;
   /**
@@ -116,6 +125,11 @@ interface Task {
   createdAt: Date;
   createdBy: string | null;
   description: string | null;
+  /**
+   * Whether `dueAt` is a calendar date (stored as midnight UTC) rather than a
+   * moment. Absent or null: a midnight-UTC `dueAt` is read as a date.
+   */
+  dueAllDay?: boolean | null;
   dueAt: Date | null;
   entityId: string | null;
   entityType: TaskEntityType | null;
@@ -203,6 +217,11 @@ interface CreateTaskInput {
   assignee?: string;
   createdBy?: string;
   description?: string;
+  /**
+   * Whether `dueAt` is a calendar date (stored as midnight UTC) rather than a
+   * moment. Absent or null: a midnight-UTC `dueAt` is read as a date.
+   */
+  dueAllDay?: boolean | null;
   dueAt?: Date;
   entityId?: string;
   entityType?: TaskEntityType;
@@ -212,6 +231,11 @@ interface CreateTaskInput {
 interface UpdateTaskInput {
   assignee?: string | null;
   description?: string | null;
+  /**
+   * Whether `dueAt` is a calendar date (stored as midnight UTC) rather than a
+   * moment. Absent or null: a midnight-UTC `dueAt` is read as a date.
+   */
+  dueAllDay?: boolean | null;
   dueAt?: Date | null;
   entityId?: string | null;
   entityType?: TaskEntityType | null;
@@ -244,6 +268,17 @@ interface ContactFilters {
    * row is no longer sync-provenanced.
    */
   excludeArchived?: boolean;
+  /**
+   * Case-insensitive substring match on name or email.
+   *
+   * Applied in SQL, not over an already-fetched page: a filter applied after
+   * paging returns a partial page and a cursor that skips the rows it dropped,
+   * so "page 2" of a search is not the second page of the matches. An empty or
+   * whitespace-only value is ignored rather than matching nothing.
+   *
+   * LIKE metacharacters in the term are escaped and matched literally — a
+   * search for `%` finds contacts containing a percent sign, not every row.
+   */
   search?: string;
   source?: RecordSource;
   status?: ContactStatus;