@kelpie/server 0.6.0 → 0.7.0

package/src/modules/import-export/schema.ts

@@ -4,6 +4,7 @@ import {
   IMPORT_OBJECTS,
   IMPORT_ROW_ACTIONS,
   IMPORT_SOURCES,
+  ON_MISSING_COMPANY,
 } from '@kelpie/schemas'
 import type {
   ImportColumnMap,
@@ -68,12 +69,21 @@ export const importJobs = pgTable(
     object: text('object').notNull(),
     status: text('status').notNull(),
     conflictMode: text('conflict_mode').notNull(),
+    /**
+     * What a People import does with a row naming a company that is not here
+     * yet: `skip` leaves the affiliation unlinked and warns, `create` invents
+     * the company. Defaulted so a job predating this reads as `skip`, which is
+     * the behaviour every other object already has.
+     */
+    onMissingCompany: text('on_missing_company').notNull().default('skip'),
     matchKey: text('match_key').notNull(),
     columnMap: jsonb('column_map').$type<ImportColumnMap>().notNull().default({}),
     sourceHeaders: jsonb('source_headers').$type<readonly string[]>().notNull().default([]),
     counts: jsonb('counts').$type<ImportCounts>().notNull(),
     /** The first `IMPORT_REPORTED_ERRORS` failing rows. `counts.error` is the true number. */
     errors: jsonb('errors').$type<readonly ImportRowError[]>().notNull().default([]),
+    /** The first `IMPORT_REPORTED_ERRORS` non-fatal notes, e.g. a person imported with the position skipped. */
+    warnings: jsonb('warnings').$type<readonly ImportRowError[]>().notNull().default([]),
     /** The first `IMPORT_PREVIEW_ROWS` rows, mapped as Kelpie read them. */
     preview: jsonb('preview').$type<readonly ImportPreviewRow[]>().notNull().default([]),
     /**
@@ -97,6 +107,7 @@ export const importJobs = pgTable(
     checkOneOf('import_jobs_source_check', table.source, IMPORT_SOURCES),
     checkOneOf('import_jobs_object_check', table.object, IMPORT_OBJECTS),
     checkOneOf('import_jobs_conflict_mode_check', table.conflictMode, IMPORT_CONFLICT_MODES),
+    checkOneOf('import_jobs_on_missing_company_check', table.onMissingCompany, ON_MISSING_COMPANY),
     checkOneOf('import_jobs_status_check', table.status, IMPORT_JOB_STATUSES),
   ],
 )
@@ -128,6 +139,8 @@ export const importJobRows = pgTable(
     values: jsonb('values').$type<Readonly<Record<string, string>>>().notNull().default({}),
     action: text('action').notNull(),
     errors: jsonb('errors').$type<readonly StoredRowError[]>().notNull().default([]),
+    /** Non-fatal notes about a row that was applied anyway, e.g. an unlinked position. */
+    warnings: jsonb('warnings').$type<readonly StoredRowError[]>().notNull().default([]),
     createdAt: createdAt(),
     updatedAt: updatedAt(),
   },

package/src/modules/import-export/service.ts

@@ -17,6 +17,7 @@ import type {
   ImportRowError,
   ImportSource,
   MatchKeyOption,
+  OnMissingCompany,
 } from '@kelpie/schemas'
 
 import type { Database } from '../../lib/database.ts'
@@ -142,12 +143,14 @@ export interface ImportJobView {
   readonly object: ImportObject
   readonly status: string
   readonly conflictMode: ImportConflictMode
+  readonly onMissingCompany: OnMissingCompany
   readonly matchKey: string
   readonly columnMap: ImportColumnMap
   readonly sourceHeaders: readonly string[]
   readonly fileName: string | null
   readonly counts: ImportCounts
   readonly errors: readonly ImportRowError[]
+  readonly warnings: readonly ImportRowError[]
   readonly preview: readonly ImportPreviewRow[]
   readonly createdAt: Date
   readonly updatedAt: Date
@@ -157,6 +160,7 @@ export interface CreateImportJobInput {
   readonly source: ImportSource
   readonly object: ImportObject
   readonly conflictMode: ImportConflictMode
+  readonly onMissingCompany: OnMissingCompany
   readonly matchKeyId: string
   /** Absent means "derive one from the source preset and the file's own headers". */
   readonly columnMap: ImportColumnMap | undefined
@@ -213,6 +217,7 @@ function toView(job: ImportJobRecord): ImportJobView {
     source: rest.source as ImportSource,
     object: rest.object as ImportObject,
     conflictMode: rest.conflictMode as ImportConflictMode,
+    onMissingCompany: rest.onMissingCompany as OnMissingCompany,
   }
 }
 
@@ -358,11 +363,37 @@ export function createImportExportService(
   ): Promise<ImportLookups> {
     const existing = await findExistingKeys(db, workspaceId, object, matchKey, rows)
 
-    if (object === 'companies' || object === 'people') {
+    if (object === 'companies') {
       return {
         existing,
         personIdByEmail: new Map(),
         companyIdByDomain: new Map(),
+        companyIdByName: new Map(),
+        memberIdByEmail: new Map(),
+        dealStageIdByName: new Map(),
+      }
+    }
+
+    // People only need companies, and only when a row carries an affiliation.
+    // Both a domain map and a name map, because a row may identify its company
+    // either way.
+    if (object === 'people') {
+      const domains = distinct(rows.map((row) => normaliseDomain(row.mapped.company_domain ?? '')))
+      const names = distinct(
+        rows.map((row) => (row.mapped.company_name ?? '').trim().toLowerCase() || null),
+      )
+      const [byDomain, byName] = await Promise.all([
+        repository.findCompanyIdsByDomain(db, workspaceId, domains),
+        repository.findCompanyIdsByName(db, workspaceId, names),
+      ])
+
+      return {
+        existing,
+        personIdByEmail: new Map(),
+        companyIdByDomain: new Map(
+          byDomain.flatMap((row) => (row.domain === null ? [] : [[row.domain, row.id] as const])),
+        ),
+        companyIdByName: new Map(byName.map((row) => [row.name.toLowerCase(), row.id] as const)),
         memberIdByEmail: new Map(),
         dealStageIdByName: new Map(),
       }
@@ -389,6 +420,7 @@ export function createImportExportService(
         companyIdByDomain: new Map(
           companyRows.flatMap((row) => (row.domain === null ? [] : [[row.domain, row.id] as const])),
         ),
+        companyIdByName: new Map(),
         memberIdByEmail: new Map(),
         dealStageIdByName: new Map(),
       }
@@ -416,6 +448,7 @@ export function createImportExportService(
       companyIdByDomain: new Map(
         companyRows.flatMap((row) => (row.domain === null ? [] : [[row.domain, row.id] as const])),
       ),
+      companyIdByName: new Map(),
       memberIdByEmail: new Map(members.map((member) => [member.email.toLowerCase(), member.id])),
       dealStageIdByName: stagesByName,
     }
@@ -426,6 +459,7 @@ export function createImportExportService(
       object: job.object as ImportObject,
       matchKey: requireMatchKey(job.object as ImportObject, job.matchKey),
       conflictMode: job.conflictMode as ImportConflictMode,
+      onMissingCompany: job.onMissingCompany as OnMissingCompany,
       lookups,
     }
   }
@@ -469,10 +503,13 @@ export function createImportExportService(
   }
 
   function toOutcome(planned: PlannedRow): repository.RowOutcome {
+    const { plan } = planned
+
     return {
       rowNumber: planned.row,
-      action: planned.plan.action,
-      errors: planned.plan.action === 'error' ? planned.plan.errors : [],
+      action: plan.action,
+      errors: plan.action === 'error' ? plan.errors : [],
+      warnings: plan.action === 'create' || plan.action === 'update' ? (plan.warnings ?? []) : [],
     }
   }
 
@@ -486,7 +523,11 @@ export function createImportExportService(
   function reportOf(
     outcomes: readonly repository.RowOutcome[],
     mapped: readonly MappedRow[],
-  ): { errors: readonly ImportRowError[]; preview: readonly ImportPreviewRow[] } {
+  ): {
+    errors: readonly ImportRowError[]
+    warnings: readonly ImportRowError[]
+    preview: readonly ImportPreviewRow[]
+  } {
     const byRow = new Map(mapped.map((row) => [row.row, row.mapped]))
 
     return {
@@ -500,6 +541,16 @@ export function createImportExportService(
             message: problem.message,
           })),
         ),
+      warnings: outcomes
+        .filter((outcome) => outcome.warnings.length > 0)
+        .slice(0, IMPORT_REPORTED_ERRORS)
+        .flatMap((outcome) =>
+          outcome.warnings.map((problem) => ({
+            row: outcome.rowNumber,
+            field: problem.field,
+            message: problem.message,
+          })),
+        ),
       preview: outcomes.slice(0, IMPORT_PREVIEW_ROWS).map((outcome) => ({
         row: outcome.rowNumber,
         action: outcome.action,
@@ -601,6 +652,8 @@ export function createImportExportService(
         rowNumber: line.number,
         action: plan.action,
         errors: plan.action === 'error' ? plan.errors : [],
+        warnings:
+          plan.action === 'create' || plan.action === 'update' ? (plan.warnings ?? []) : [],
       }
 
       if (plan.action !== 'error' && plan.action !== 'skip') {
@@ -629,6 +682,16 @@ export function createImportExportService(
             written.changedFields,
           )
         }
+
+        // A People affiliation makes a Position, and maybe a Company. Each is its
+        // own record with its own module event, whatever the person row did.
+        for (const side of written.sideRecords ?? []) {
+          if (side.created) {
+            emitImportedRecordCreated(events, side.objectType, side.recordId)
+          } else if (side.changedFields.length > 0) {
+            emitImportedRecordUpdated(events, side.objectType, side.recordId, side.changedFields)
+          }
+        }
       }
 
       // In the same transaction as the record it wrote, so the account of the
@@ -682,6 +745,7 @@ export function createImportExportService(
             rowNumber: row.row,
             action: 'error' as const,
             errors: [{ field: '', message: describeThrown(error) }],
+            warnings: [],
           }
 
           // Its own statement: the transaction that would have carried this one
@@ -786,11 +850,13 @@ export function createImportExportService(
         object: input.object,
         status: 'pending',
         conflictMode: input.conflictMode,
+        onMissingCompany: input.onMissingCompany,
         matchKey: matchKey.id,
         columnMap,
         sourceHeaders: parsed.headers,
         counts: { ...EMPTY_COUNTS, total: parsed.rows.length },
         errors: [],
+        warnings: [],
         preview: [],
         fileSha256: fileDigest(input.csv),
         fileName: input.fileName,

package/src/modules/import-export/tools.ts

@@ -3,6 +3,7 @@ import {
   IMPORT_OBJECTS,
   IMPORT_SOURCES,
   MAX_IMPORT_FILE_BYTES,
+  ON_MISSING_COMPANY,
   defaultMatchKeyId,
 } from '@kelpie/schemas'
 import { z } from 'zod'
@@ -59,6 +60,13 @@ const previewArgs = z.strictObject({
     .enum(IMPORT_CONFLICT_MODES)
     .default('skip')
     .describe('What to do with a row that matches an existing record.'),
+  on_missing_company: z
+    .enum(ON_MISSING_COMPANY)
+    .default('skip')
+    .describe(
+      'People import only: what to do when a row names a company that is not here yet. ' +
+        "'skip' imports the person and leaves the position unlinked; 'create' invents the company.",
+    ),
   match_key: z.string().min(1).optional().describe('Which field decides that match.'),
   column_map: columnMapArg.optional(),
   file_name: z.string().min(1).nullable().default(null).describe('Recorded on the job, for the log.'),
@@ -124,6 +132,7 @@ export function registerImportExportTools(mcp: McpToolRegistry, service: ImportE
           source: args.source,
           object: args.object,
           conflictMode: args.conflict_mode,
+          onMissingCompany: args.on_missing_company,
           matchKeyId: args.match_key ?? defaultMatchKeyId(args.object),
           columnMap: args.column_map,
           fileName: args.file_name,

package/src/modules/import-export/writes.ts

@@ -11,7 +11,7 @@ import * as dealRepository from '../deals/repository.ts'
 import * as peopleRepository from '../people/repository.ts'
 import * as positionRepository from '../positions/repository.ts'
 import { IMPORT_DEAL_CURRENCY, NEW_COMPANY_DEFAULTS, NEW_PERSON_DEFAULTS } from './drafts.ts'
-import type { ImportWrite, RowPlan } from './plan.ts'
+import type { ImportWrite, PlannedAffiliation, RowPlan } from './plan.ts'
 
 /**
  * Applying one planned row: the insert or update, and the timeline entry that
@@ -34,6 +34,21 @@ export interface WriteDependencies {
   readonly sourceName: string
 }
 
+/**
+ * A record a row wrote besides its primary one.
+ *
+ * A People row with an affiliation makes a Position, and under
+ * `on_missing_company: create` a Company as well. Each needs its own module
+ * event, which the service emits from these.
+ */
+export interface SideRecord {
+  readonly objectType: RecordObjectType
+  readonly recordId: string
+  readonly created: boolean
+  /** The columns an update moved. Empty on a create. */
+  readonly changedFields: readonly string[]
+}
+
 export interface WriteOutcome {
   readonly recordId: string
   readonly objectType: RecordObjectType
@@ -43,6 +58,8 @@ export interface WriteOutcome {
    * nothing at all.
    */
   readonly changedFields: readonly string[]
+  /** Records the row wrote besides its primary one: a People affiliation's company and position. */
+  readonly sideRecords?: readonly SideRecord[]
 }
 
 /** A create or update plan. `skip` and `error` never reach here. */
@@ -102,6 +119,92 @@ async function writeCompany(
   return { recordId: id, objectType: 'company', changedFields }
 }
 
+/**
+ * Writes the position a People row named, and the company it belongs to when the
+ * job was told to create one.
+ *
+ * The company is created before the position so the link has something to point
+ * at. The position is renamed in place when the person already holds one at that
+ * company, and created otherwise, which is the two-column-key behaviour the
+ * People affiliation chose. Files the `created Company` and `linked to company`
+ * activities as it goes, the same sentences the Companies and Positions imports
+ * write.
+ */
+async function applyAffiliation(
+  dependencies: WriteDependencies,
+  personId: string,
+  affiliation: PlannedAffiliation,
+): Promise<readonly SideRecord[]> {
+  const { tx, workspaceId, actor, sourceName } = dependencies
+  const sideRecords: SideRecord[] = []
+
+  const companyId = await (async (): Promise<string> => {
+    if (affiliation.kind === 'link') {
+      return affiliation.companyId
+    }
+
+    const created = await companyRepository.insertCompany(tx, {
+      ...NEW_COMPANY_DEFAULTS,
+      ...affiliation.company,
+      tags: affiliation.company.tags === undefined ? undefined : [...affiliation.company.tags],
+      id: dependencies.createId('company'),
+      workspaceId,
+      name: affiliation.company.name ?? '',
+    })
+
+    sideRecords.push({ objectType: 'company', recordId: created.id, created: true, changedFields: [] })
+    await dependencies.recordActivity(tx, workspaceId, actor, {
+      targetType: 'company',
+      targetId: created.id,
+      kind: 'created',
+      ...describeCreationVia('Company', sourceName),
+    })
+
+    return created.id
+  })()
+
+  const held = await positionRepository.listPositionsAt(tx, workspaceId, personId, companyId)
+  const current = held[0]
+
+  if (current === undefined) {
+    const created = await positionRepository.insertPosition(tx, {
+      id: dependencies.createId('position'),
+      workspaceId,
+      personId,
+      companyId,
+      title: affiliation.title,
+    })
+
+    sideRecords.push({ objectType: 'position', recordId: created.id, created: true, changedFields: [] })
+
+    for (const end of [
+      { targetType: 'person', targetId: personId, related: 'company' },
+      { targetType: 'company', targetId: companyId, related: 'person' },
+    ] as const) {
+      await dependencies.recordActivity(tx, workspaceId, actor, {
+        targetType: end.targetType,
+        targetId: end.targetId,
+        kind: 'linked',
+        ...describeLink(end.related, sourceName),
+      })
+    }
+
+    return sideRecords
+  }
+
+  const changedFields = changedKeys(current, { title: affiliation.title })
+
+  if (changedFields.length > 0) {
+    await positionRepository.updatePosition(tx, workspaceId, current.id, {
+      title: affiliation.title,
+      updatedAt: dependencies.now,
+    })
+    sideRecords.push({ objectType: 'position', recordId: current.id, created: false, changedFields })
+  }
+
+  return sideRecords
+}
+
 async function writePerson(
   dependencies: WriteDependencies,
   plan: WritablePlan,
@@ -120,7 +223,12 @@ async function writePerson(
       name: write.draft.name ?? '',
     })
 
-    return { recordId: created.id, objectType: 'person', changedFields: [] }
+    const sideRecords =
+      write.affiliation === undefined
+        ? []
+        : await applyAffiliation(dependencies, created.id, write.affiliation)
+
+    return { recordId: created.id, objectType: 'person', changedFields: [], sideRecords }
   }
 
   const id = requireTarget(plan)
@@ -144,7 +252,12 @@ async function writePerson(
     })
   }
 
-  return { recordId: id, objectType: 'person', changedFields }
+  const sideRecords =
+    write.affiliation === undefined
+      ? []
+      : await applyAffiliation(dependencies, id, write.affiliation)
+
+  return { recordId: id, objectType: 'person', changedFields, sideRecords }
 }
 
 /**

package/src/testing/app.ts

@@ -3,7 +3,7 @@ import type { Context, Hono } from 'hono'
 import { createApp } from '../app.ts'
 import type { AppBindings } from '../app.ts'
 import type { Actor } from '../lib/actor.ts'
-import type { Environment } from '../lib/config.ts'
+import type { Environment, RuntimeMode } from '../lib/config.ts'
 import type { DatabaseProbe } from '../lib/database.ts'
 import { createCaptureTransport, createLogger } from '../lib/logger.ts'
 import { rateLimitConfigFrom, rateLimitConfigSchema } from '../lib/rateLimit.ts'
@@ -57,6 +57,10 @@ export interface TestAppOptions {
   readonly rateLimit?: RateLimitConfig
   /** Defaults to reading `X-Forwarded-For`, so a test can simulate distinct callers. */
   readonly resolveClientIp?: (context: Context) => string
+  /** Reported through `GET /v1/public/config`. Defaults to `'production'`. */
+  readonly runtimeMode?: RuntimeMode
+  /** Reported through `GET /v1/public/config`. Defaults to unset. */
+  readonly siteName?: string
 }
 
 export interface TestApp {
@@ -102,6 +106,8 @@ export async function createTestApp(options: TestAppOptions = {}): Promise<TestA
     createId: services.createId,
     rateLimit: options.rateLimit ?? DEFAULT_TEST_RATE_LIMIT,
     resolveClientIp: options.resolveClientIp ?? testClientIp,
+    ...(options.runtimeMode === undefined ? {} : { runtimeMode: options.runtimeMode }),
+    ...(options.siteName === undefined ? {} : { siteName: options.siteName }),
   })
 
   return { app, contributions, logLines, services }