@clivly/core 0.14.1 → 0.15.0

package/README.md

@@ -48,7 +48,7 @@ client.
 | Entry | Contents |
 | --- | --- |
 | `@clivly/core` | The re-exported surface: contracts, entity config, mapping form, sync engine, view compiler, projections, shared types |
-| `@clivly/core/adapter` | `CRMAdapter` — the interface every ORM implementation fulfils (org-scoped; contacts, companies, deals, tasks, activities). List reads are keyset-paged: `listContactsPage`, `listCompaniesPage`, `listDealsPage` and `listTasksPage` take a `PageRequest` and return a `Page` |
+| `@clivly/core/adapter` | `CRMAdapter` — the interface every ORM implementation fulfils (org-scoped; contacts, companies, deals, tasks, activities). List reads are keyset-paged: `listContactsPage`, `listCompaniesPage`, `listDealsPage` and `listTasksPage` take a `PageRequest` and return a `Page`; `countContacts` returns how many contacts match the same `ContactFilters` |
 | `@clivly/core/auth-adapter` | `ClivlyAuthAdapter`, `ClivlyUser`, `authCustom()`, `MembershipResolver`, `CrmMembership` — pluggable host-app identity + the `crm_members` authorization layer |
 | `@clivly/core/entity-config` | `defineClivlyConfig`, `validateEntitiesConfig`, `entitiesConfigSchema`, `CANONICAL_FIELDS`, `CRM_CONCEPTS`, `ClivlyConfigError`, and the config types |
 | `@clivly/core/types` | Shared domain types (`Contact`, `Company`, `Deal`, `Task`, `Note`, `Activity`, inputs, filters, `CrmRole`) |

package/dist/adapter.d.cts

@@ -19,6 +19,20 @@ export 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/dist/adapter.d.mts

@@ -19,6 +19,20 @@ export 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/dist/index.cjs

@@ -33,6 +33,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/dist/index.d.cts

@@ -17,7 +17,7 @@ import { EntitySyncResult, MirrorRecord, PersistAction, ResolvedMembership, Sour
  * 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;
@@ -26,6 +26,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/dist/index.d.mts

@@ -17,7 +17,7 @@ import { EntitySyncResult, MirrorRecord, PersistAction, ResolvedMembership, Sour
  * 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;
@@ -26,6 +26,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/dist/index.mjs

@@ -32,6 +32,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/dist/integration-state.cjs

@@ -346,6 +346,7 @@ exports.DEFAULT_HEARTBEAT_INTERVAL_MS = DEFAULT_HEARTBEAT_INTERVAL_MS;
 exports.INSTALL_COMMAND = INSTALL_COMMAND;
 exports.INTEGRATION_STEPS = INTEGRATION_STEPS;
 exports.INTEGRATION_STEP_LABELS = INTEGRATION_STEP_LABELS;
+exports.LIVE_INTERVALS = LIVE_INTERVALS;
 exports.STEP_PREREQUISITES = STEP_PREREQUISITES;
 exports.computeIntegrationState = computeIntegrationState;
 exports.deriveLiveness = deriveLiveness;

package/dist/integration-state.d.cts

@@ -111,6 +111,7 @@ export interface IntegrationStep {
 export declare function formatAge(ms: number): string;
 /** The cadence `createClivlySDK` uses when the host app configures none. */
 export declare const DEFAULT_HEARTBEAT_INTERVAL_MS = 60000;
+export declare const LIVE_INTERVALS = 2.5;
 export type ConnectionHealth = "live" | "live_with_issues" | "stale" | "offline";
 /**
  * Clivly's own answer to "is this app up", obtained by asking it rather than

package/dist/integration-state.d.mts

@@ -111,6 +111,7 @@ export interface IntegrationStep {
 export declare function formatAge(ms: number): string;
 /** The cadence `createClivlySDK` uses when the host app configures none. */
 export declare const DEFAULT_HEARTBEAT_INTERVAL_MS = 60000;
+export declare const LIVE_INTERVALS = 2.5;
 export type ConnectionHealth = "live" | "live_with_issues" | "stale" | "offline";
 /**
  * Clivly's own answer to "is this app up", obtained by asking it rather than

package/dist/integration-state.mjs

@@ -341,4 +341,4 @@ function computeIntegrationState(facts) {
 	};
 }
 //#endregion
-export { DEFAULT_HEARTBEAT_INTERVAL_MS, INSTALL_COMMAND, INTEGRATION_STEPS, INTEGRATION_STEP_LABELS, STEP_PREREQUISITES, computeIntegrationState, deriveLiveness, deriveStatus, formatAge, livenessWindows, nextAction, resolveSteps, stepIndex };
+export { DEFAULT_HEARTBEAT_INTERVAL_MS, INSTALL_COMMAND, INTEGRATION_STEPS, INTEGRATION_STEP_LABELS, LIVE_INTERVALS, STEP_PREREQUISITES, computeIntegrationState, deriveLiveness, deriveStatus, formatAge, livenessWindows, nextAction, resolveSteps, stepIndex };

package/dist/types.d.cts

@@ -84,12 +84,21 @@ export interface Company {
 }
 export 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 @@ export 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 @@ export 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 @@ export interface CreateTaskInput {
 export 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 @@ export 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/dist/types.d.mts

@@ -84,12 +84,21 @@ export interface Company {
 }
 export 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 @@ export 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 @@ export 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 @@ export interface CreateTaskInput {
 export 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 @@ export 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/package.json

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