@marlinjai/contacts-core 0.1.0 → 0.2.0

package/dist/index.cjs

@@ -37,10 +37,20 @@ __export(src_exports, {
   ContactError: () => ContactError,
   ContactsLayoutError: () => ContactsLayoutError,
   CsvError: () => CsvError,
+  FIELD_KEY: () => FIELD_KEY,
+  FIELD_LABEL_MAX: () => FIELD_LABEL_MAX,
+  FIELD_OPTIONS_MAX: () => FIELD_OPTIONS_MAX,
+  FIELD_OPTION_MAX: () => FIELD_OPTION_MAX,
+  FIELD_TEXT_MAX: () => FIELD_TEXT_MAX,
+  FIELD_TYPES: () => FIELD_TYPES,
+  FIELD_URL_MAX: () => FIELD_URL_MAX,
   IMPORT_COLUMNS: () => IMPORT_COLUMNS,
   MIGRATIONS: () => MIGRATIONS,
   MigrationError: () => MigrationError,
   ORGANIZATION_NAME_MAX: () => ORGANIZATION_NAME_MAX,
+  PREFERRED_CONTACT: () => PREFERRED_CONTACT,
+  applyCustomFieldPatch: () => applyCustomFieldPatch,
+  checkFieldValue: () => checkFieldValue,
   contactIdentityKey: () => contactIdentityKey,
   contactsFor: () => contactsFor,
   createContactsDb: () => createContactsDb,
@@ -52,12 +62,15 @@ __export(src_exports, {
   migrate: () => migrate,
   missingMigrations: () => missingMigrations,
   normalizeContactInput: () => normalizeContactInput,
+  normalizeFieldDefinition: () => normalizeFieldDefinition,
   parseCsv: () => parseCsv,
   uuidv7: () => uuidv7
 });
 module.exports = __toCommonJS(src_exports);
 
 // src/model.ts
+var PREFERRED_CONTACT = ["email", "phone", "post", "none"];
+var FIELD_TYPES = ["text", "number", "date", "boolean", "select", "multi_select", "url"];
 var ContactError = class extends Error {
   code;
   /** For `duplicate`: the contact that already carries this identity. For `stale`: the current record. */
@@ -136,9 +149,15 @@ function normalizeContactInput(input) {
     postalCode: optional(input.postalCode, "postalCode", 20),
     city: optional(input.city, "city", SHORT_FIELD_MAX),
     country,
-    vatId: optional(input.vatId, "vatId", 40)
+    vatId: optional(input.vatId, "vatId", 40),
+    preferredContact: preferredContact(input.preferredContact)
   };
 }
+function preferredContact(value) {
+  if (value === null || value === void 0) return null;
+  if (PREFERRED_CONTACT.includes(value)) return value;
+  throw new ContactError("invalid_field", { field: "preferredContact" });
+}
 function contactIdentityKey(kind, name, companyOrRole = "") {
   const n = collapse(name).toLocaleLowerCase("de-DE");
   if (kind === "organization") return n;
@@ -151,6 +170,108 @@ function formatCustomerNumber(n, width = 4) {
   return String(n).padStart(width, "0");
 }
 
+// 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 collapse2 = (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 = collapse2(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) => collapse2(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
 var import_kysely = require("kysely");
 var import_kysely_postgres_js = require("kysely-postgres-js");
@@ -212,6 +333,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))
+);
 `
   }
 ];
@@ -377,13 +529,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,
@@ -398,6 +562,8 @@ function columns(data) {
     city: data.city,
     country: data.country,
     vat_id: data.vatId,
+    preferred_contact: data.preferredContact,
+    custom_fields: import_kysely2.sql`${JSON.stringify(customFields)}::text::jsonb`,
     identity_key: contactIdentityKey(data.kind, data.name, data.companyOrRole)
   };
 }
@@ -418,6 +584,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);
@@ -489,7 +659,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 });
@@ -513,7 +684,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: import_kysely2.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: import_kysely2.sql`version + 1`, updated_at: /* @__PURE__ */ new Date() }).where("tenant_id", "=", tenantId).where("id", "=", id).returningAll().executeTakeFirstOrThrow();
           return toContact(updated);
         });
       } catch (e) {
@@ -524,6 +697,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 : import_kysely2.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) {
@@ -801,10 +1008,20 @@ async function importContacts(contacts, rows, options = {}) {
   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,
@@ -816,6 +1033,7 @@ async function importContacts(contacts, rows, options = {}) {
   migrate,
   missingMigrations,
   normalizeContactInput,
+  normalizeFieldDefinition,
   parseCsv,
   uuidv7
 });