@kelpie/server 0.6.0 → 0.8.0

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

@@ -174,6 +174,33 @@ export function personDraft(mapped: Readonly<Record<string, string>>): PersonDra
   })
 }
 
+/**
+ * The company a People row's affiliation would create.
+ *
+ * Built from the row's `company_domain` and `company_name` cells, not the
+ * `name`/`domain` a Companies file uses. The name falls back to the raw domain
+ * so a create from a domain-only row is not a nameless company. The write lays
+ * `NEW_COMPANY_DEFAULTS` over this, the same as a Companies import.
+ */
+export function affiliationCompanyDraft(mapped: Readonly<Record<string, string>>): CompanyDraft {
+  const domainRaw = text(mapped, 'company_domain')
+
+  return present<CompanyDraft>({
+    name: text(mapped, 'company_name') ?? domainRaw,
+    domain: domainRaw === undefined ? undefined : (normaliseDomain(domainRaw) ?? undefined),
+    industry: undefined,
+    description: undefined,
+    stage: undefined,
+    sizeBand: undefined,
+    hq: undefined,
+    website: undefined,
+    accountType: undefined,
+    icpFit: undefined,
+    summary: undefined,
+    tags: undefined,
+  })
+}
+
 /**
  * `value` is required, so `moneyToCents` has already been checked by
  * `validateRow` and cannot be undefined here.

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

@@ -26,8 +26,17 @@ function joinList(values: readonly string[]): string {
   return values.join('|')
 }
 
+/**
+ * The header row of an export and of a template.
+ *
+ * `importOnly` columns are left out: a People import may map `company_domain`,
+ * `company_name` and `title` to drive a Position, but a person holds many
+ * positions and none of them is a field on the person. Writing one on the export
+ * would be lossy, so the export and the template carry the round-trippable
+ * columns only, and each cell function matches this order one for one.
+ */
 export function headersFor(object: ImportObject): readonly string[] {
-  return OBJECT_COLUMNS[object].map((column) => column.key)
+  return OBJECT_COLUMNS[object].filter((column) => column.importOnly !== true).map((column) => column.key)
 }
 
 export function companyCells(row: ExportCompanyRow): readonly string[] {

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

@@ -3,10 +3,11 @@ import type {
   ImportCounts,
   ImportObject,
   MatchKeyOption,
+  OnMissingCompany,
 } from '@kelpie/schemas'
 
 import { normaliseDomain, normaliseEmail } from '../../lib/normalisation.ts'
-import { companyDraft, dealFieldsDraft, personDraft } from './drafts.ts'
+import { affiliationCompanyDraft, companyDraft, dealFieldsDraft, personDraft } from './drafts.ts'
 import type { CompanyDraft, DealFieldsDraft, PersonDraft } from './drafts.ts'
 import { buildMatchKey, splitList } from './mapping.ts'
 import { aliasedStageSlug } from './presets.ts'
@@ -29,6 +30,8 @@ export interface ImportLookups {
   readonly existing: ReadonlyMap<string, string>
   readonly personIdByEmail: ReadonlyMap<string, string>
   readonly companyIdByDomain: ReadonlyMap<string, string>
+  /** Company id by its folded name, for a People affiliation matched by name. */
+  readonly companyIdByName: ReadonlyMap<string, string>
   /** Workspace member id by the address of the user behind it. */
   readonly memberIdByEmail: ReadonlyMap<string, string>
   /** Deal stage id, keyed by both its slug and its folded label. */
@@ -39,13 +42,28 @@ export interface PlanContext {
   readonly object: ImportObject
   readonly matchKey: MatchKeyOption
   readonly conflictMode: ImportConflictMode
+  /** What a People row does with an absent company. Ignored by the other objects. */
+  readonly onMissingCompany: OnMissingCompany
   readonly lookups: ImportLookups
 }
 
+/**
+ * A company affiliation a People row asks for: the position to write, and
+ * whether the company must be created before it can be linked.
+ */
+export type PlannedAffiliation =
+  | { readonly kind: 'link'; readonly companyId: string; readonly title: string }
+  | { readonly kind: 'create'; readonly company: CompanyDraft; readonly title: string }
+
 /** The values a write applies, once every reference in the row has been resolved. */
 export type ImportWrite =
   | { readonly object: 'companies'; readonly draft: CompanyDraft }
-  | { readonly object: 'people'; readonly draft: PersonDraft }
+  | {
+      readonly object: 'people'
+      readonly draft: PersonDraft
+      /** A position to upsert alongside the person, when the row named a company and a title. */
+      readonly affiliation?: PlannedAffiliation
+    }
   | {
       readonly object: 'positions'
       readonly personId: string
@@ -78,12 +96,19 @@ export type RowPlan =
    * reaches the row the earlier one has been written, so it resolves to an id.
    */
   | { readonly action: 'skip'; readonly key: string; readonly targetId: string | null }
-  | { readonly action: 'create'; readonly key: string; readonly write: ImportWrite }
+  | {
+      readonly action: 'create'
+      readonly key: string
+      readonly write: ImportWrite
+      /** Non-fatal notes about the applied row, e.g. a People affiliation left unlinked. */
+      readonly warnings?: readonly StoredRowError[]
+    }
   | {
       readonly action: 'update'
       readonly key: string
       readonly targetId: string | null
       readonly write: ImportWrite
+      readonly warnings?: readonly StoredRowError[]
     }
 
 export interface PlannedRow {
@@ -233,6 +258,80 @@ function resolveWrite(context: PlanContext, mapped: Readonly<Record<string, stri
   }
 }
 
+/**
+ * The company affiliation a People row asks for, if any, and any note about it.
+ *
+ * A row states an affiliation only when it carries both a title and a company
+ * identity, so a blank optional cell still says nothing, the additive rule every
+ * column follows. The company is matched by domain when the row has one and by
+ * name otherwise. A named company that is not here follows `on_missing_company`:
+ * `create` invents it from the row, `skip` imports the person alone and returns
+ * a warning.
+ */
+function planAffiliation(
+  context: PlanContext,
+  mapped: Readonly<Record<string, string>>,
+): { readonly affiliation?: PlannedAffiliation; readonly warnings: readonly StoredRowError[] } {
+  const title = (mapped.title ?? '').trim()
+  const domainRaw = (mapped.company_domain ?? '').trim()
+  const nameRaw = (mapped.company_name ?? '').trim()
+
+  if (title.length === 0 || (domainRaw.length === 0 && nameRaw.length === 0)) {
+    return { warnings: [] }
+  }
+
+  const domain = normaliseDomain(domainRaw)
+  const companyId =
+    domainRaw.length > 0
+      ? domain === null
+        ? undefined
+        : context.lookups.companyIdByDomain.get(domain)
+      : context.lookups.companyIdByName.get(nameRaw.toLowerCase())
+
+  if (companyId !== undefined) {
+    return { affiliation: { kind: 'link', companyId, title }, warnings: [] }
+  }
+
+  if (context.onMissingCompany === 'create') {
+    return {
+      affiliation: { kind: 'create', company: affiliationCompanyDraft(mapped), title },
+      warnings: [],
+    }
+  }
+
+  const named = domainRaw.length > 0 ? domainRaw : nameRaw
+
+  return {
+    warnings: [
+      {
+        field: domainRaw.length > 0 ? 'company_domain' : 'company_name',
+        message: `No company here matches "${named}", so the person imported without a position`,
+      },
+    ],
+  }
+}
+
+/**
+ * Folds a People row's affiliation into its create or update plan.
+ *
+ * A no-op for every other object, and for a person the row said nothing about a
+ * company for. The affiliation rides on the write; any note rides on the plan.
+ */
+function withAffiliation(
+  context: PlanContext,
+  mapped: Readonly<Record<string, string>>,
+  plan: Extract<RowPlan, { action: 'create' } | { action: 'update' }>,
+): RowPlan {
+  if (context.object !== 'people' || plan.write.object !== 'people') {
+    return plan
+  }
+
+  const { affiliation, warnings } = planAffiliation(context, mapped)
+  const write = affiliation === undefined ? plan.write : { ...plan.write, affiliation }
+
+  return { ...plan, write, ...(warnings.length > 0 ? { warnings } : {}) }
+}
+
 /**
  * @param mapped The row's cells by Kelpie column, from `mapRow`.
  * @returns What this row would do. `create` when its key matches nothing;
@@ -265,15 +364,18 @@ export function planRow(context: PlanContext, mapped: Readonly<Record<string, st
   const targetId = context.lookups.existing.get(key)
 
   if (targetId === undefined) {
-    return { action: 'create', key, write }
+    return withAffiliation(context, mapped, { action: 'create', key, write })
   }
 
   // An empty string is the placeholder an in-file match carries: the record it
   // matched has not been written yet, so there is no id to report.
   const resolved = targetId.length === 0 ? null : targetId
 
+  // A skipped row is left entirely alone, affiliation included. A caller who
+  // wants an existing person's position updated runs the job in `update` mode,
+  // which is where the rename-in-place lives.
   return context.conflictMode === 'update'
-    ? { action: 'update', key, targetId: resolved, write }
+    ? withAffiliation(context, mapped, { action: 'update', key, targetId: resolved, write })
     : { action: 'skip', key, targetId: resolved }
 }
 

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

@@ -31,6 +31,8 @@ export const SOURCE_PRESETS: Readonly<Record<ImportSource, SourcePreset>> = {
       email: 'Email',
       phones: 'Phone Number',
       location: 'City',
+      company_domain: 'Company Domain Name',
+      title: 'Job Title',
     },
     positions: {
       person_email: 'Email',
@@ -60,6 +62,8 @@ export const SOURCE_PRESETS: Readonly<Record<ImportSource, SourcePreset>> = {
       email: 'Email',
       phones: 'Phone',
       location: 'Mailing City',
+      company_name: 'Account Name',
+      title: 'Title',
     },
     positions: {
       person_email: 'Email',
@@ -76,6 +80,27 @@ export const SOURCE_PRESETS: Readonly<Record<ImportSource, SourcePreset>> = {
       external_id: 'Opportunity ID',
     },
   },
+  attio: {
+    // Attio's export writes one column per attribute, and a linked or nested
+    // attribute as `Parent > Child`. Only Companies and People are mapped: the
+    // sample export carries no Deals or Positions file, and an Attio People row
+    // names its company but not the company's domain, so a Position could not be
+    // keyed from it. Those objects fall back to `custom`.
+    companies: {
+      name: 'Record',
+      domain: 'Domains',
+      industry: 'Categories',
+      description: 'Description',
+      hq: 'Primary location > Country',
+    },
+    people: {
+      name: 'Record',
+      email: 'Email addresses',
+      location: 'Primary location > Country',
+      company_name: 'Company > Name',
+      title: 'Job title',
+    },
+  },
 }
 
 /**

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

@@ -175,6 +175,8 @@ export interface RowOutcome {
   readonly rowNumber: number
   readonly action: SettledRowAction
   readonly errors: readonly { readonly field: string; readonly message: string }[]
+  /** Non-fatal notes about a row that was applied anyway, e.g. an unlinked position. */
+  readonly warnings: readonly { readonly field: string; readonly message: string }[]
 }
 
 /**
@@ -202,12 +204,18 @@ export async function recordRowOutcome(
       values,
       action: outcome.action,
       errors: outcome.errors,
+      warnings: outcome.warnings,
       createdAt: now,
       updatedAt: now,
     })
     .onConflictDoUpdate({
       target: [importJobRows.jobId, importJobRows.rowNumber],
-      set: { action: outcome.action, errors: outcome.errors, updatedAt: now },
+      set: {
+        action: outcome.action,
+        errors: outcome.errors,
+        warnings: outcome.warnings,
+        updatedAt: now,
+      },
     })
 }
 
@@ -381,6 +389,32 @@ export function findCompanyIdsByDomain(
   )
 }
 
+/**
+ * Company ids by folded name, for a People affiliation matched on a company
+ * name rather than a domain.
+ *
+ * `lower(name) in (…)` rather than `ilike`, so a `%` inside a caller-supplied
+ * name is a literal, not a wildcard. The same rule `findCompanyKeys` follows.
+ * The caller passes names already lowercased.
+ */
+export function findCompanyIdsByName(
+  db: Queryable,
+  workspaceId: string,
+  names: readonly string[],
+): Promise<{ name: string; id: string }[]> {
+  return overChunks(names, (chunk) =>
+    db
+      .select({ id: companies.id, name: companies.name })
+      .from(companies)
+      .where(
+        and(
+          eq(companies.workspaceId, workspaceId),
+          inArray(sql<string>`lower(${companies.name})`, [...chunk]),
+        ),
+      ),
+  )
+}
+
 /** Every member of the workspace, by the address of the user behind them. */
 export function listMemberEmails(
   db: Queryable,

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

@@ -3,6 +3,7 @@ import {
   IMPORT_OBJECTS,
   IMPORT_SOURCES,
   MAX_IMPORT_FILE_BYTES,
+  ON_MISSING_COMPANY,
   defaultMatchKeyId,
 } from '@kelpie/schemas'
 import type { ImportColumnMap, ImportObject } from '@kelpie/schemas'
@@ -42,6 +43,7 @@ const createJobForm = z.object({
   source: z.enum(IMPORT_SOURCES),
   object: z.enum(IMPORT_OBJECTS),
   conflict_mode: z.enum(IMPORT_CONFLICT_MODES).default('skip'),
+  on_missing_company: z.enum(ON_MISSING_COMPANY).default('skip'),
   match_key: z.string().min(1).optional(),
   column_map: z.string().optional(),
   dry_run: z.enum(['true', 'false']).default('true'),
@@ -58,12 +60,14 @@ export function importJobResponse(job: ImportJobView): Record<string, unknown> {
     object: job.object,
     status: job.status,
     conflict_mode: job.conflictMode,
+    on_missing_company: job.onMissingCompany,
     match_key: job.matchKey,
     column_map: job.columnMap,
     source_headers: job.sourceHeaders,
     file_name: job.fileName,
     counts: job.counts,
     errors: job.errors,
+    warnings: job.warnings,
     preview: job.preview,
     created_at: job.createdAt.toISOString(),
     updated_at: job.updatedAt.toISOString(),
@@ -230,6 +234,7 @@ export function mountImportExportRoutes(
       source: parsed.data.source,
       object: parsed.data.object,
       conflictMode: parsed.data.conflict_mode,
+      onMissingCompany: parsed.data.on_missing_company,
       matchKeyId: parsed.data.match_key ?? defaultMatchKeyId(parsed.data.object),
       columnMap: readColumnMap(parsed.data.column_map),
       fileName: file.name.length === 0 ? null : file.name,

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,