@marlinjai/contacts-core 0.1.0 → 0.2.0

package/dist/index.d.ts

@@ -1,8 +1,59 @@
-import { Contact, ContactKind, ContactInput } from './model.js';
-export { CONTACT_COMPANY_MAX, CONTACT_EMAIL_MAX, CONTACT_NAME_MAX, CONTACT_NOTE_MAX, ContactError, ContactErrorCode, NormalizedContact, ORGANIZATION_NAME_MAX, contactIdentityKey, formatCustomerNumber, formatGuest, isContactId, normalizeContactInput } from './model.js';
-import { Kysely, Generated, ColumnType } from 'kysely';
+import { FieldType, FieldValues, FieldValue, Contact, ContactKind, ContactInput } from './model.js';
+export { CONTACT_COMPANY_MAX, CONTACT_EMAIL_MAX, CONTACT_NAME_MAX, CONTACT_NOTE_MAX, ContactError, ContactErrorCode, FIELD_TYPES, NormalizedContact, ORGANIZATION_NAME_MAX, PREFERRED_CONTACT, PreferredContact, contactIdentityKey, formatCustomerNumber, formatGuest, isContactId, normalizeContactInput } from './model.js';
+import { Kysely, Generated, ColumnType, Expression } from 'kysely';
 import { Sql } from 'postgres';
 
+/**
+ * Custom field definitions and the checks that every stored value must pass.
+ *
+ * The type names are the data table's column type names (`ColumnType` in
+ * @marlinjai/data-table-core), which export no value validation, so the rules
+ * live here. A value is either accepted exactly as given, or refused with a
+ * typed error that names the field. Nothing is coerced: a number is never read
+ * from a string, and a date must be a real calendar day.
+ */
+declare const FIELD_KEY: RegExp;
+declare const FIELD_LABEL_MAX = 80;
+declare const FIELD_OPTION_MAX = 80;
+declare const FIELD_OPTIONS_MAX = 100;
+declare const FIELD_TEXT_MAX = 2000;
+declare const FIELD_URL_MAX = 2048;
+interface FieldDefinition {
+    key: string;
+    label: string;
+    type: FieldType;
+    /** Choices for select and multi_select; null for every other type. */
+    options: string[] | null;
+    archived: boolean;
+    createdAt: Date;
+}
+interface FieldDefinitionInput {
+    key: string;
+    label: string;
+    type: string;
+    options?: readonly string[] | null;
+}
+interface NormalizedFieldDefinition {
+    key: string;
+    label: string;
+    type: FieldType;
+    options: string[] | null;
+}
+/** Validates a definition before it is stored. Throws ContactError('invalid_field' | 'too_long'). */
+declare function normalizeFieldDefinition(input: FieldDefinitionInput): NormalizedFieldDefinition;
+/** Checks one value against its definition. Returns the value as stored. Throws ContactError. */
+declare function checkFieldValue(def: FieldDefinition, value: unknown): FieldValue;
+/**
+ * Applies a patch of custom field values to a contact's current values.
+ *
+ * - A key without a definition is refused (`unknown_field`), never dropped.
+ * - A key whose definition is archived is refused (`field_archived`) when a value
+ *   is set. Clearing it (null) is allowed, so an archived field can be emptied.
+ * - A null value removes the key. Keys not in the patch are left as they are,
+ *   including values under archived definitions.
+ */
+declare function applyCustomFieldPatch(current: FieldValues, patch: Record<string, unknown>, definitions: readonly FieldDefinition[]): FieldValues;
+
 /**
  * The table changes of the contacts database, in order.
  *
@@ -44,18 +95,33 @@ interface ContactsTable {
     country: string | null;
     vat_id: string | null;
     customer_number: number | null;
+    preferred_contact: string | null;
+    /** Written as a cast JSON expression (see columns in contacts.ts); read back as the parsed object. */
+    custom_fields: ColumnType<Record<string, unknown>, Expression<unknown> | undefined, Expression<unknown>>;
     identity_key: string;
     version: Generated<number>;
     archived_at: ColumnType<Date | null, Date | string | null | undefined, Date | string | null>;
     created_at: Timestamp;
     updated_at: Timestamp;
 }
+interface ContactFieldDefinitionsTable {
+    tenant_id: string;
+    id: string;
+    key: string;
+    label: string;
+    type: string;
+    /** Written as a cast JSON expression; read back as the parsed array (null for non-choice types). */
+    options: ColumnType<string[] | null, Expression<unknown> | null | undefined, Expression<unknown> | null>;
+    archived_at: ColumnType<Date | null, Date | string | null | undefined, Date | string | null>;
+    created_at: Timestamp;
+}
 interface TenantCountersTable {
     tenant_id: string;
     next_customer_number: Generated<number>;
 }
 interface Database {
     contacts: ContactsTable;
+    contact_field_definitions: ContactFieldDefinitionsTable;
     tenant_counters: TenantCountersTable;
 }
 /**
@@ -153,6 +219,14 @@ interface Contacts {
     setCustomerNumber(id: string, customerNumber: number): Promise<Contact>;
     /** The number the next `assignCustomerNumber` would hand out. */
     peekNextCustomerNumber(): Promise<number>;
+    /** Defines a custom field for this company. Its key is unique per company; a key of an archived field stays taken. */
+    createField(input: FieldDefinitionInput): Promise<FieldDefinition>;
+    /** The company's custom fields. Archived ones are left out unless asked for. */
+    listFields(options?: {
+        includeArchived?: boolean;
+    }): Promise<FieldDefinition[]>;
+    /** Archives a custom field by key. Stored values stay; new values are refused. */
+    archiveField(key: string): Promise<FieldDefinition>;
     /** Deletes one contact for good. Persons linked to an erased organization keep their record, unlinked. */
     erase(id: string): Promise<boolean>;
     /** Deletes every contact and the counter of this company. Safe to repeat. Returns the number of contacts removed. */
@@ -234,4 +308,4 @@ declare function importContacts(contacts: Contacts, rows: readonly ImportRow[],
  */
 declare function uuidv7(now?: number): string;
 
-export { Contact, type ContactExport, ContactInput, ContactKind, type Contacts, type ContactsDb, type ContactsDbOptions, ContactsLayoutError, CsvError, IMPORT_COLUMNS, type ImportReport, type ImportRow, type ListOptions, MIGRATIONS, type MigrateResult, type Migration, MigrationError, type MigrationSource, contactsFor, createContactsDb, importContacts, loadMigrations, migrate, missingMigrations, parseCsv, uuidv7 };
+export { Contact, type ContactExport, ContactInput, ContactKind, type Contacts, type ContactsDb, type ContactsDbOptions, ContactsLayoutError, CsvError, FIELD_KEY, FIELD_LABEL_MAX, FIELD_OPTIONS_MAX, FIELD_OPTION_MAX, FIELD_TEXT_MAX, FIELD_URL_MAX, type FieldDefinition, type FieldDefinitionInput, FieldType, FieldValue, FieldValues, IMPORT_COLUMNS, type ImportReport, type ImportRow, type ListOptions, MIGRATIONS, type MigrateResult, type Migration, MigrationError, type MigrationSource, type NormalizedFieldDefinition, applyCustomFieldPatch, checkFieldValue, contactsFor, createContactsDb, importContacts, loadMigrations, migrate, missingMigrations, normalizeFieldDefinition, parseCsv, uuidv7 };

package/dist/index.js

@@ -4,13 +4,117 @@ import {
   CONTACT_NAME_MAX,
   CONTACT_NOTE_MAX,
   ContactError,
+  FIELD_TYPES,
   ORGANIZATION_NAME_MAX,
+  PREFERRED_CONTACT,
   contactIdentityKey,
   formatCustomerNumber,
   formatGuest,
   isContactId,
   normalizeContactInput
-} from "./chunk-FPZSYMBL.js";
+} from "./chunk-5LG5GEWU.js";
+
+// src/fields.ts
+var FIELD_KEY = /^[a-z][a-z0-9_]{1,39}$/;
+var FIELD_LABEL_MAX = 80;
+var FIELD_OPTION_MAX = 80;
+var FIELD_OPTIONS_MAX = 100;
+var FIELD_TEXT_MAX = 2e3;
+var FIELD_URL_MAX = 2048;
+var collapse = (text) => text.replace(/\s+/g, " ").trim();
+function normalizeFieldDefinition(input) {
+  const key = String(input.key ?? "");
+  if (!FIELD_KEY.test(key)) throw new ContactError("invalid_field", { field: "key" });
+  const label = collapse(String(input.label ?? ""));
+  if (!label) throw new ContactError("invalid_field", { field: "label" });
+  if (label.length > FIELD_LABEL_MAX) throw new ContactError("too_long", { field: "label" });
+  if (!FIELD_TYPES.includes(input.type)) {
+    throw new ContactError("invalid_field", { field: "type" });
+  }
+  const type = input.type;
+  const choosable = type === "select" || type === "multi_select";
+  if (!choosable) {
+    if (input.options !== void 0 && input.options !== null) {
+      throw new ContactError("invalid_field", { field: "options" });
+    }
+    return { key, label, type, options: null };
+  }
+  if (!Array.isArray(input.options) || input.options.length === 0 || input.options.length > FIELD_OPTIONS_MAX) {
+    throw new ContactError("invalid_field", { field: "options" });
+  }
+  const options = input.options.map((o) => collapse(String(o)));
+  for (const option of options) {
+    if (!option) throw new ContactError("invalid_field", { field: "options" });
+    if (option.length > FIELD_OPTION_MAX) throw new ContactError("too_long", { field: "options" });
+  }
+  if (new Set(options).size !== options.length) throw new ContactError("invalid_field", { field: "options" });
+  return { key, label, type, options };
+}
+var ISO_DAY = /^(\d{4})-(\d{2})-(\d{2})$/;
+function checkFieldValue(def, value) {
+  const refuse = () => new ContactError("invalid_value", { field: def.key });
+  switch (def.type) {
+    case "text": {
+      if (typeof value !== "string" || value.length === 0 || value.length > FIELD_TEXT_MAX) throw refuse();
+      if (value !== value.trim()) throw refuse();
+      return value;
+    }
+    case "number": {
+      if (typeof value !== "number" || !Number.isFinite(value)) throw refuse();
+      return value;
+    }
+    case "date": {
+      if (typeof value !== "string") throw refuse();
+      const match = ISO_DAY.exec(value);
+      if (!match) throw refuse();
+      const [year, month, day] = [Number(match[1]), Number(match[2]), Number(match[3])];
+      const date = new Date(Date.UTC(year, month - 1, day));
+      if (date.getUTCFullYear() !== year || date.getUTCMonth() !== month - 1 || date.getUTCDate() !== day) throw refuse();
+      return value;
+    }
+    case "boolean": {
+      if (typeof value !== "boolean") throw refuse();
+      return value;
+    }
+    case "select": {
+      if (typeof value !== "string" || !def.options?.includes(value)) throw refuse();
+      return value;
+    }
+    case "multi_select": {
+      if (!Array.isArray(value) || value.length === 0) throw refuse();
+      if (!value.every((v) => typeof v === "string" && def.options?.includes(v))) throw refuse();
+      if (new Set(value).size !== value.length) throw refuse();
+      return [...value];
+    }
+    case "url": {
+      if (typeof value !== "string" || value.length > FIELD_URL_MAX) throw refuse();
+      let parsed;
+      try {
+        parsed = new URL(value);
+      } catch {
+        throw refuse();
+      }
+      if (parsed.protocol !== "https:" && parsed.protocol !== "http:") throw refuse();
+      return value;
+    }
+  }
+}
+function applyCustomFieldPatch(current, patch, definitions) {
+  const byKey = new Map(definitions.map((d) => [d.key, d]));
+  const next = { ...current };
+  for (const [key, value] of Object.entries(patch)) {
+    if (value === void 0) continue;
+    const def = byKey.get(key);
+    if (!def) throw new ContactError("unknown_field", { field: key });
+    if (value === null) {
+      delete next[key];
+      continue;
+    }
+    if (def.archived) throw new ContactError("field_archived", { field: key });
+    next[key] = checkFieldValue(def, value);
+  }
+  return next;
+}
 
 // src/db.ts
 import { Kysely } from "kysely";
@@ -73,6 +177,37 @@ CREATE TABLE tenant_counters (
   tenant_id             text PRIMARY KEY CHECK (char_length(tenant_id) BETWEEN 1 AND 64),
   next_customer_number  integer NOT NULL DEFAULT 1 CHECK (next_customer_number > 0)
 );
+`
+  },
+  {
+    name: "0002_contact_fields",
+    sql: `
+-- A preferred way to be contacted. Null means none was recorded.
+ALTER TABLE contacts
+  ADD COLUMN preferred_contact text CHECK (preferred_contact IN ('email', 'phone', 'post', 'none'));
+
+-- Values of the company's custom fields, keyed by field key. Checked against the
+-- definitions by the package on every write, so the column itself only insists on an object.
+ALTER TABLE contacts
+  ADD COLUMN custom_fields jsonb NOT NULL DEFAULT '{}'::jsonb CHECK (jsonb_typeof(custom_fields) = 'object');
+
+-- One definition per field and company. Archived definitions stay, so the values
+-- stored under them keep their meaning; the package refuses new values for them.
+CREATE TABLE contact_field_definitions (
+  tenant_id    text NOT NULL CHECK (char_length(tenant_id) BETWEEN 1 AND 64),
+  id           uuid NOT NULL,
+  key          text NOT NULL CHECK (key ~ '^[a-z][a-z0-9_]{1,39}$'),
+  label        text NOT NULL CHECK (char_length(label) BETWEEN 1 AND 80),
+  type         text NOT NULL CHECK (type IN ('text', 'number', 'date', 'boolean', 'select', 'multi_select', 'url')),
+  -- Choices for select and multi_select; absent for every other type.
+  options      jsonb CHECK (options IS NULL OR jsonb_typeof(options) = 'array'),
+  archived_at  timestamptz,
+  created_at   timestamptz NOT NULL DEFAULT now(),
+  PRIMARY KEY (tenant_id, id),
+  CONSTRAINT contact_field_definitions_key UNIQUE (tenant_id, key),
+  CONSTRAINT contact_field_definitions_options
+    CHECK ((type IN ('select', 'multi_select')) = (options IS NOT NULL))
+);
 `
   }
 ];
@@ -238,13 +373,25 @@ function toContact(row) {
     country: row.country,
     vatId: row.vat_id,
     customerNumber: row.customer_number,
+    preferredContact: row.preferred_contact,
+    customFields: row.custom_fields ?? {},
     version: row.version,
     archived: row.archived_at !== null,
     createdAt: row.created_at,
     updatedAt: row.updated_at
   };
 }
-function columns(data) {
+function toDefinition(row) {
+  return {
+    key: row.key,
+    label: row.label,
+    type: row.type,
+    options: row.options,
+    archived: row.archived_at !== null,
+    createdAt: row.created_at
+  };
+}
+function columns(data, customFields) {
   return {
     name: data.name,
     company_or_role: data.companyOrRole,
@@ -259,6 +406,8 @@ function columns(data) {
     city: data.city,
     country: data.country,
     vat_id: data.vatId,
+    preferred_contact: data.preferredContact,
+    custom_fields: sql`${JSON.stringify(customFields)}::text::jsonb`,
     identity_key: contactIdentityKey(data.kind, data.name, data.companyOrRole)
   };
 }
@@ -279,6 +428,10 @@ function contactsFor(handle, tenantId) {
   }
   const { db } = handle;
   const own = (trx = db) => trx.selectFrom("contacts").selectAll().where("tenant_id", "=", tenantId);
+  async function loadDefinitions(trx = db) {
+    const rows = await trx.selectFrom("contact_field_definitions").selectAll().where("tenant_id", "=", tenantId).orderBy("created_at").orderBy("key").execute();
+    return rows.map(toDefinition);
+  }
   async function findByIdentity(kind, name, companyOrRole, exceptId) {
     let q = own().where("kind", "=", kind).where("identity_key", "=", contactIdentityKey(kind, name, companyOrRole));
     if (exceptId) q = q.where("id", "!=", exceptId);
@@ -350,7 +503,8 @@ function contactsFor(handle, tenantId) {
       if (!isContactId(id)) throw new ContactError("invalid_field", { field: "id" });
       await handle.ready();
       await assertOrganization(data.organizationId);
-      const inserted = await db.insertInto("contacts").values({ id, tenant_id: tenantId, kind: data.kind, ...columns(data) }).onConflict((oc) => oc.columns(["tenant_id", "kind", "identity_key"]).doNothing()).returningAll().executeTakeFirst();
+      const customFields = input.customFields ? applyCustomFieldPatch({}, input.customFields, await loadDefinitions()) : {};
+      const inserted = await db.insertInto("contacts").values({ id, tenant_id: tenantId, kind: data.kind, ...columns(data, customFields) }).onConflict((oc) => oc.columns(["tenant_id", "kind", "identity_key"]).doNothing()).returningAll().executeTakeFirst();
       if (!inserted) {
         const existing = await findByIdentity(data.kind, data.name, data.companyOrRole);
         throw new ContactError("duplicate", { existing: existing ?? void 0 });
@@ -374,7 +528,9 @@ function contactsFor(handle, tenantId) {
             const org = await own(trx).where("id", "=", data.organizationId).executeTakeFirst();
             if (!org || org.kind !== "organization") throw new ContactError("invalid_organization");
           }
-          const updated = await trx.updateTable("contacts").set({ ...columns(data), version: sql`version + 1`, updated_at: /* @__PURE__ */ new Date() }).where("tenant_id", "=", tenantId).where("id", "=", id).returningAll().executeTakeFirstOrThrow();
+          const currentFields = row.custom_fields ?? {};
+          const customFields = input.customFields ? applyCustomFieldPatch(currentFields, input.customFields, await loadDefinitions(trx)) : currentFields;
+          const updated = await trx.updateTable("contacts").set({ ...columns(data, customFields), version: sql`version + 1`, updated_at: /* @__PURE__ */ new Date() }).where("tenant_id", "=", tenantId).where("id", "=", id).returningAll().executeTakeFirstOrThrow();
           return toContact(updated);
         });
       } catch (e) {
@@ -385,6 +541,40 @@ function contactsFor(handle, tenantId) {
         throw e;
       }
     },
+    async createField(input) {
+      await handle.ready();
+      const data = normalizeFieldDefinition(input);
+      try {
+        const row = await db.insertInto("contact_field_definitions").values({
+          tenant_id: tenantId,
+          id: uuidv7(),
+          key: data.key,
+          label: data.label,
+          type: data.type,
+          options: data.options === null ? null : sql`${JSON.stringify(data.options)}::text::jsonb`
+        }).returningAll().executeTakeFirstOrThrow();
+        return toDefinition(row);
+      } catch (e) {
+        if (e.constraint_name === "contact_field_definitions_key") {
+          throw new ContactError("duplicate_field", { field: data.key });
+        }
+        throw e;
+      }
+    },
+    async listFields(options = {}) {
+      await handle.ready();
+      const definitions = await loadDefinitions();
+      return options.includeArchived ? definitions : definitions.filter((d) => !d.archived);
+    },
+    /** Archives a field: its stored values stay, and new values under it are refused. Repeating it changes nothing. */
+    async archiveField(key) {
+      await handle.ready();
+      const row = await db.selectFrom("contact_field_definitions").selectAll().where("tenant_id", "=", tenantId).where("key", "=", key).executeTakeFirst();
+      if (!row) throw new ContactError("field_not_found", { field: key });
+      if (row.archived_at !== null) return toDefinition(row);
+      const updated = await db.updateTable("contact_field_definitions").set({ archived_at: /* @__PURE__ */ new Date() }).where("tenant_id", "=", tenantId).where("key", "=", key).returningAll().executeTakeFirstOrThrow();
+      return toDefinition(updated);
+    },
     archive: (id) => setArchived(id, true),
     restore: (id) => setArchived(id, false),
     async merge(loserId, winnerId) {
@@ -661,10 +851,20 @@ export {
   ContactError,
   ContactsLayoutError,
   CsvError,
+  FIELD_KEY,
+  FIELD_LABEL_MAX,
+  FIELD_OPTIONS_MAX,
+  FIELD_OPTION_MAX,
+  FIELD_TEXT_MAX,
+  FIELD_TYPES,
+  FIELD_URL_MAX,
   IMPORT_COLUMNS,
   MIGRATIONS,
   MigrationError,
   ORGANIZATION_NAME_MAX,
+  PREFERRED_CONTACT,
+  applyCustomFieldPatch,
+  checkFieldValue,
   contactIdentityKey,
   contactsFor,
   createContactsDb,
@@ -676,6 +876,7 @@ export {
   migrate,
   missingMigrations,
   normalizeContactInput,
+  normalizeFieldDefinition,
   parseCsv,
   uuidv7
 };