@kelpie/server 0.1.0

package/src/modules/decisions/tools.ts

@@ -0,0 +1,38 @@
+import { RECORD_TARGET_TYPES } from '@kelpie/schemas'
+import { z } from 'zod'
+
+import type { McpToolRegistry } from '../../runtime/module.ts'
+import { idArg, idSetArg, listWindowShape, registerCrudTools, termArg, toSet } from '../crudTools.ts'
+import { createBody, decisionResponse, toCreateInput, toUpdateInput, updateBody } from './routes.ts'
+import type { DecisionsService } from './service.ts'
+
+/** `decisions_*`. Same schemas and mappers as `/v1/decisions`. */
+
+const listArgs = z.strictObject({
+  ...listWindowShape,
+  q: termArg,
+  target_type: z.enum(RECORD_TARGET_TYPES).optional().describe('Decisions on this kind of record.'),
+  target_id: idSetArg.optional().describe('The decisions on these records.'),
+})
+
+export function registerDecisionsTools(mcp: McpToolRegistry, service: DecisionsService): void {
+  registerCrudTools(mcp, {
+    resource: 'decisions',
+    subject: 'decision',
+    about:
+      'A commitment this company has already made. Read the open ones before proposing ' +
+      'anything; contradicting one is worse than saying nothing.',
+    service,
+    render: decisionResponse,
+    listArgs,
+    toFilters: (args) => ({
+      term: args.q,
+      targetType: args.target_type,
+      targetIds: toSet(args.target_id),
+    }),
+    createArgs: createBody,
+    toCreateInput,
+    updateArgs: updateBody.extend({ id: idArg }),
+    toUpdateInput,
+  })
+}

package/src/modules/forms/embed.ts

@@ -0,0 +1,274 @@
+import type { FormFieldRecord, FormRecord } from './repository.ts'
+
+/**
+ * The hosted embed page and the snippets that put it on a customer's site.
+ *
+ * Server-rendered and self-contained on purpose. A site embedding a Kelpie form
+ * frames a page from the Kelpie origin, and that page must not drag the CRM's
+ * React bundle into somebody else's marketing site to draw five inputs.
+ *
+ * Everything here is pure: a form, its fields, and a URL in; a string out. That
+ * is what makes the escaping testable, which for a page built by string
+ * concatenation is the part worth testing.
+ */
+
+/** `'` as `'` rather than `'`, which older HTML parsers do not know. */
+const HTML_ESCAPES: Readonly<Record<string, string>> = {
+  '&': '&amp;',
+  '<': '&lt;',
+  '>': '&gt;',
+  '"': '&quot;',
+  "'": '&#39;',
+}
+
+/**
+ * Escapes text for both element content and quoted attribute values.
+ *
+ * Every value a form author typed reaches this page, so a label of
+ * `"><script>…` would otherwise be a stored cross-site scripting hole against
+ * whoever embeds the form. One function for both positions because the set of
+ * characters that break out of either is the same.
+ */
+export function escapeHtml(text: string): string {
+  return text.replaceAll(/[&<>"']/gu, (match) => HTML_ESCAPES[match] ?? match)
+}
+
+/**
+ * Escapes a string for a `<script>` body.
+ *
+ * An HTML parser ends a script at the literal `</script`, wherever it appears,
+ * including inside a JSON string. Breaking the sequence is what keeps embedded
+ * data from closing the element that carries it.
+ */
+function escapeScriptJson(value: unknown): string {
+  return JSON.stringify(value).replaceAll('<', '\\u003c').replaceAll('\u2028', '\\u2028').replaceAll('\u2029', '\\u2029')
+}
+
+function renderOptions(field: FormFieldRecord): string {
+  const blank = field.required ? '' : '<option value="">—</option>'
+  const choices = field.options
+    .map((option) => `<option value="${escapeHtml(option.key)}">${escapeHtml(option.value)}</option>`)
+    .join('')
+
+  return blank + choices
+}
+
+function renderControl(field: FormFieldRecord): string {
+  const shared = [
+    `id="${escapeHtml(field.id)}"`,
+    `name="${escapeHtml(field.id)}"`,
+    ...(field.required ? ['required'] : []),
+    ...(field.placeholder === null ? [] : [`placeholder="${escapeHtml(field.placeholder)}"`]),
+  ].join(' ')
+
+  if (field.type === 'select') {
+    return `<select ${shared}>${renderOptions(field)}</select>`
+  }
+
+  if (field.type === 'textarea') {
+    return `<textarea ${shared} rows="4"></textarea>`
+  }
+
+  // `type="email"` gives a phone keyboard the @ key and catches a typo before a
+  // round trip. The server validates the address regardless.
+  return `<input ${shared} type="${field.type === 'email' ? 'email' : 'text'}">`
+}
+
+function renderField(field: FormFieldRecord): string {
+  const required = field.required ? '<span class="req" aria-hidden="true">*</span>' : ''
+
+  return [
+    '<div class="field">',
+    `<label for="${escapeHtml(field.id)}">${escapeHtml(field.label)}${required}</label>`,
+    renderControl(field),
+    '</div>',
+  ].join('')
+}
+
+/**
+ * Styles for the page. Deliberately plain and system-font: this renders inside
+ * somebody else's design, and a form that tries to bring its own brand fights
+ * the site it was embedded in.
+ */
+const EMBED_STYLES = `
+:root { color-scheme: light dark; }
+* { box-sizing: border-box; }
+body { margin: 0; padding: 16px; font: 15px/1.5 -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif; }
+form { display: grid; gap: 14px; max-width: 32rem; margin: 0 auto; }
+.field { display: grid; gap: 5px; }
+label { font-weight: 600; font-size: 0.875rem; }
+.req { color: #b4232c; margin-left: 2px; }
+input, textarea, select { width: 100%; padding: 9px 10px; border: 1px solid #b9bfc9; border-radius: 6px; font: inherit; background: Field; color: FieldText; }
+input:focus-visible, textarea:focus-visible, select:focus-visible { outline: 2px solid #2f6feb; outline-offset: 1px; }
+textarea { resize: vertical; }
+button { padding: 10px 16px; border: 0; border-radius: 6px; background: #2f6feb; color: #fff; font: inherit; font-weight: 600; cursor: pointer; }
+button[disabled] { opacity: 0.6; cursor: progress; }
+.note { margin: 0; font-size: 0.875rem; }
+.error { color: #b4232c; }
+.done { max-width: 32rem; margin: 0 auto; }
+`
+
+/**
+ * The browser half of the page.
+ *
+ * Plain `fetch` and no dependencies, so the page loads nothing from anywhere and
+ * a strict Content-Security-Policy can refuse every external origin. The height
+ * is posted to the parent because an iframe cannot size itself; the companion
+ * listener ships in `scriptSnippet`.
+ */
+const EMBED_SCRIPT = `
+(function () {
+  var config = JSON.parse(document.getElementById('kelpie-config').textContent);
+  var form = document.getElementById('kelpie-form');
+  var status = document.getElementById('kelpie-status');
+  var button = document.getElementById('kelpie-submit');
+
+  function postHeight() {
+    parent.postMessage({ kelpie: 'height', formId: config.formId, height: document.documentElement.scrollHeight }, '*');
+  }
+
+  new ResizeObserver(postHeight).observe(document.documentElement);
+
+  form.addEventListener('submit', function (event) {
+    event.preventDefault();
+    status.textContent = '';
+    status.className = 'note';
+    button.disabled = true;
+
+    var answers = {};
+    config.fieldIds.forEach(function (id) {
+      var value = form.elements[id].value.trim();
+      if (value) { answers[id] = value; }
+    });
+
+    fetch(config.submitUrl, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ answers: answers })
+    }).then(function (response) {
+      return response.json().then(function (body) { return { ok: response.ok, body: body }; });
+    }).then(function (result) {
+      if (!result.ok) {
+        throw new Error((result.body && result.body.error && result.body.error.message) || 'Something went wrong.');
+      }
+      var done = document.createElement('div');
+      done.className = 'done';
+      done.textContent = result.body.thank_you_message || config.thankYou;
+      form.replaceWith(done);
+      parent.postMessage({ kelpie: 'submitted', formId: config.formId }, '*');
+      postHeight();
+    }).catch(function (error) {
+      status.textContent = error.message;
+      status.className = 'note error';
+      button.disabled = false;
+    });
+  });
+})();
+`
+
+export interface EmbedPageOptions {
+  readonly form: FormRecord
+  readonly fields: readonly FormFieldRecord[]
+  /** Absolute URL of the public submit endpoint this page posts to. */
+  readonly submitUrl: string
+  /** Per-response value tying the inline style and script to the CSP header. */
+  readonly nonce: string
+}
+
+/**
+ * The whole page, as one document.
+ *
+ * A paused form still renders. Somebody visiting the page a customer's site
+ * already embeds should be told the form is closed rather than shown a working
+ * form whose submit answers 409.
+ */
+export function renderEmbedPage(options: EmbedPageOptions): string {
+  const { form, fields, submitUrl, nonce } = options
+  const config = escapeScriptJson({
+    formId: form.id,
+    submitUrl,
+    thankYou: form.thankYouMessage,
+    fieldIds: fields.map((field) => field.id),
+  })
+  const body =
+    form.status === 'paused'
+      ? `<div class="done"><p class="note">This form is not accepting submissions right now.</p></div>`
+      : [
+          '<form id="kelpie-form" novalidate>',
+          fields.map(renderField).join(''),
+          '<div><button id="kelpie-submit" type="submit">Submit</button></div>',
+          '<p id="kelpie-status" class="note" role="status" aria-live="polite"></p>',
+          '</form>',
+          `<script type="application/json" id="kelpie-config">${config}</script>`,
+          `<script nonce="${escapeHtml(nonce)}">${EMBED_SCRIPT}</script>`,
+        ].join('')
+
+  return [
+    '<!doctype html>',
+    '<html lang="en">',
+    '<head>',
+    '<meta charset="utf-8">',
+    '<meta name="viewport" content="width=device-width, initial-scale=1">',
+    // Not indexed: the canonical page for this form is the customer's own, and
+    // a bare embed ranking above it would be a worse result for a reader.
+    '<meta name="robots" content="noindex">',
+    `<title>${escapeHtml(form.name)}</title>`,
+    `<style nonce="${escapeHtml(nonce)}">${EMBED_STYLES}</style>`,
+    '</head>',
+    `<body>${body}</body>`,
+    '</html>',
+  ].join('')
+}
+
+/**
+ * The page's Content-Security-Policy.
+ *
+ * `default-src 'none'` because the page loads nothing: no fonts, no images, no
+ * scripts from anywhere. `connect-src 'self'` allows the one `fetch` back to the
+ * submit endpoint. `frame-ancestors *` is the point of the page and is why it
+ * must not also send `X-Frame-Options`.
+ */
+export function embedContentSecurityPolicy(nonce: string): string {
+  return [
+    "default-src 'none'",
+    `style-src 'nonce-${nonce}'`,
+    `script-src 'nonce-${nonce}'`,
+    "connect-src 'self'",
+    "form-action 'none'",
+    'frame-ancestors *',
+  ].join('; ')
+}
+
+/** What a customer pastes into their site. Both put the same hosted page on the page. */
+export interface EmbedSnippets {
+  readonly url: string
+  readonly iframe: string
+  readonly script: string
+}
+
+/**
+ * The two ways to embed.
+ *
+ * The iframe is the honest minimum: one tag, no JavaScript, fixed height. The
+ * script adds the listener that resizes it as fields appear and as the thank-you
+ * replaces the form, which is the only thing an iframe cannot do for itself.
+ */
+export function embedSnippets(url: string, formId: string): EmbedSnippets {
+  const iframe =
+    `<iframe src="${escapeHtml(url)}" title="Contact form" ` +
+    `style="width:100%;border:0;height:520px" loading="lazy"></iframe>`
+
+  const script = [
+    `<iframe id="kelpie-${formId}" src="${escapeHtml(url)}" title="Contact form"`,
+    `        style="width:100%;border:0;height:520px" loading="lazy"></iframe>`,
+    `<script>`,
+    `  window.addEventListener('message', function (event) {`,
+    `    if (event.data && event.data.kelpie === 'height' && event.data.formId === '${formId}') {`,
+    `      document.getElementById('kelpie-${formId}').style.height = event.data.height + 'px';`,
+    `    }`,
+    `  });`,
+    `</script>`,
+  ].join('\n')
+
+  return { url, iframe, script }
+}

package/src/modules/forms/fields.ts

@@ -0,0 +1,206 @@
+import type { ErrorDetail } from '../../lib/errors.ts'
+import type { StoredFormFieldOption } from './schema.ts'
+import { PERSON_EMAIL_TARGET } from './schema.ts'
+import type { FormFieldMapTarget, FormFieldType, FormOptionValueType } from './schema.ts'
+
+/**
+ * What a form's field list has to satisfy before it is stored.
+ *
+ * Per-form rules, which is why they are not check constraints: "at most one
+ * `person.email` mapping" is a statement about a set of rows, and the database
+ * has nowhere to hang it. Pure, so the rules that decide whether a form can ever
+ * process a submission are testable without one.
+ */
+
+/** A field as a write request carries it: no id, no position, both derived. */
+export interface FieldDraft {
+  readonly label: string
+  readonly type: FormFieldType
+  readonly required: boolean
+  readonly mapTo: FormFieldMapTarget
+  readonly options: readonly OptionDraft[]
+  readonly placeholder: string | null
+}
+
+export interface OptionDraft {
+  readonly key: string
+  readonly value: string
+  readonly valueType: FormOptionValueType
+}
+
+/**
+ * Targets a form may map more than one field to.
+ *
+ * Only `submission`, which writes no CRM field and so has nothing to collide
+ * over. Two fields both mapped to `person.name` would leave the submit picking
+ * one of them by field order, which is not a decision a form author made.
+ */
+const REPEATABLE_TARGETS: ReadonlySet<string> = new Set(['submission'])
+
+/** The two targets that establish a company for a submit to attach a Deal to. */
+const COMPANY_TARGETS: readonly string[] = ['company.name', 'company.domain']
+
+/**
+ * Everything wrong with a field list, as `api.md` field details.
+ *
+ * All of it at once: a field builder sends the whole list, so reporting one
+ * problem per request would make fixing three of them three round trips.
+ *
+ * @param fields In the order they were sent, which becomes their order on screen.
+ * @param createsDeal Whether the form the list belongs to creates Deals. A Deal
+ *   belongs to a Company, and a submit only resolves one from a `company.name`
+ *   or `company.domain` answer, so a deal-creating form without either would
+ *   quietly never create a deal. Refused here rather than discovered later by
+ *   somebody wondering where their inbound pipeline went.
+ */
+export function findFieldProblems(
+  fields: readonly FieldShape[],
+  createsDeal: boolean,
+): readonly ErrorDetail[] {
+  const problems: ErrorDetail[] = []
+  const seenTargets = new Set<string>()
+
+  if (!fields.some((field) => field.mapTo === PERSON_EMAIL_TARGET)) {
+    problems.push({
+      field: 'fields',
+      message: `A form needs exactly one field mapped to ${PERSON_EMAIL_TARGET}`,
+    })
+  }
+
+  if (createsDeal && !fields.some((field) => COMPANY_TARGETS.includes(field.mapTo))) {
+    problems.push({
+      field: 'fields',
+      message: `A form that creates deals needs a field mapped to ${COMPANY_TARGETS.join(' or ')}`,
+    })
+  }
+
+  for (const [index, field] of fields.entries()) {
+    const at = `fields.${String(index)}`
+
+    if (!REPEATABLE_TARGETS.has(field.mapTo)) {
+      if (seenTargets.has(field.mapTo)) {
+        problems.push({ field: `${at}.map_to`, message: `Another field already maps to ${field.mapTo}` })
+      }
+
+      seenTargets.add(field.mapTo)
+    }
+
+    problems.push(...findOptionProblems(field, at))
+  }
+
+  return problems
+}
+
+/** A select needs choices; everything else must not carry any. */
+function findOptionProblems(field: FieldShape, at: string): readonly ErrorDetail[] {
+  if (field.type !== 'select') {
+    return field.options.length === 0
+      ? []
+      : [{ field: `${at}.options`, message: `A ${field.type} field has no options` }]
+  }
+
+  if (field.options.length === 0) {
+    return [{ field: `${at}.options`, message: 'A select field needs at least one option' }]
+  }
+
+  const problems: ErrorDetail[] = []
+  const seenKeys = new Set<string>()
+
+  for (const [index, option] of field.options.entries()) {
+    // The key is what a stored answer holds, so a duplicate would make an
+    // existing submission ambiguous about which choice was made.
+    if (seenKeys.has(option.key)) {
+      problems.push({
+        field: `${at}.options.${String(index)}.key`,
+        message: `Another option already uses "${option.key}"`,
+      })
+    }
+
+    seenKeys.add(option.key)
+  }
+
+  return problems
+}
+
+/** A field's options as they are stored. Structurally the drafts, narrowed to the stored type. */
+export function storedOptions(
+  options: readonly OptionDraft[],
+): readonly StoredFormFieldOption[] {
+  return options.map((option) => ({
+    key: option.key,
+    value: option.value,
+    valueType: option.valueType,
+  }))
+}
+
+/**
+ * A field with its ids and tenancy stripped: everything a write can change.
+ *
+ * Both a stored row and an inbound `FieldDraft` satisfy this, which is what lets
+ * one comparison and one rule set serve both sides. `type` and `mapTo` are
+ * `string` rather than their unions because that is what a `text` column reads
+ * back as; narrowing them here would mean asserting a value that is only ever
+ * tested for equality, and the check constraint is what guarantees the column
+ * holds one of the set.
+ */
+export interface FieldShape {
+  readonly label: string
+  readonly type: string
+  readonly required: boolean
+  readonly mapTo: string
+  readonly options: readonly StoredFormFieldOption[]
+  readonly placeholder: string | null
+}
+
+/**
+ * Whether a submitted field list differs from the stored one.
+ *
+ * A write replaces the whole list, so without this a client resending what it
+ * already had would delete and reinsert every row, move every id, and publish a
+ * `record.updated` that no consumer can act on. Order counts: it is the order
+ * the embed renders, and reordering is the one edit that changes nothing else.
+ *
+ * @param stored In `sort_order`, which is the order the repository returns.
+ */
+export function fieldsDiffer(
+  stored: readonly FieldShape[],
+  drafts: readonly FieldDraft[],
+): boolean {
+  if (stored.length !== drafts.length) {
+    return true
+  }
+
+  return stored.some((field, index) => {
+    const draft = drafts[index]
+
+    return (
+      draft === undefined ||
+      field.label !== draft.label ||
+      field.type !== draft.type ||
+      field.required !== draft.required ||
+      field.mapTo !== draft.mapTo ||
+      field.placeholder !== draft.placeholder ||
+      optionsDiffer(field.options, draft.options)
+    )
+  })
+}
+
+function optionsDiffer(
+  stored: readonly StoredFormFieldOption[],
+  drafts: readonly OptionDraft[],
+): boolean {
+  if (stored.length !== drafts.length) {
+    return true
+  }
+
+  return stored.some((option, index) => {
+    const draft = drafts[index]
+
+    return (
+      draft === undefined ||
+      option.key !== draft.key ||
+      option.value !== draft.value ||
+      option.valueType !== draft.valueType
+    )
+  })
+}

package/src/modules/forms/index.ts

@@ -0,0 +1,61 @@
+import type { KelpieModule } from '../../runtime/module.ts'
+import { createActivityRecorder } from '../activities/index.ts'
+import { mountPublicFormRoutes } from './publicRoutes.ts'
+import { mountFormsRoutes } from './routes.ts'
+import * as schema from './schema.ts'
+import { createFormsService } from './service.ts'
+import { createFormSubmitService } from './submission.ts'
+import { registerFormsTools } from './tools.ts'
+
+/**
+ * Forms: embeddable inbound capture, per `forms.md`.
+ *
+ * The only core module with a public surface. Managing forms needs credentials
+ * like everything else; submitting one needs nothing but the form's `publicKey`,
+ * because the caller is a stranger's browser on a stranger's website.
+ *
+ * It requires everything a submit writes. `people`, `companies` and `positions`
+ * are the upsert; `deals` and `pipelines` are the optional deal and the stage it
+ * opens in; `activities` is the timeline entry, in the same transaction as the
+ * records it describes. `workspace` arrives through those.
+ */
+export function createFormsModule(migrationsDirectory: string): KelpieModule {
+  return {
+    id: 'forms',
+    requires: ['people', 'companies', 'positions', 'pipelines', 'deals', 'activities'],
+
+    register(context) {
+      const service = createFormsService({
+        db: context.db,
+        transaction: context.transaction,
+        createId: context.createId,
+        now: context.now,
+      })
+
+      const submissions = createFormSubmitService({
+        db: context.db,
+        transaction: context.transaction,
+        createId: context.createId,
+        now: context.now,
+        recordActivity: createActivityRecorder({
+          createId: context.createId,
+          now: context.now,
+        }),
+      })
+
+      context.schema(schema, migrationsDirectory)
+
+      context.routes((router) => {
+        mountFormsRoutes(router, { db: context.db, now: context.now, service })
+      })
+
+      context.publicRoutes((router) => {
+        mountPublicFormRoutes(router, { db: context.db, submissions })
+      })
+
+      registerFormsTools(context.mcp, service)
+
+      return Promise.resolve()
+    },
+  }
+}