@kelpie/schemas 0.6.0 → 0.8.0

package/src/importExport.ts

@@ -13,10 +13,21 @@ import type { RecordTimestamps } from './wire.ts'
  * — a caller sends a `column_map` and never has to know how one was derived.
  */
 
-export const IMPORT_SOURCES = ['custom', 'hubspot', 'salesforce'] as const
+export const IMPORT_SOURCES = ['custom', 'hubspot', 'salesforce', 'attio'] as const
 export const IMPORT_OBJECTS = ['companies', 'people', 'positions', 'deals'] as const
 export const IMPORT_CONFLICT_MODES = ['skip', 'update'] as const
 
+/**
+ * What a People import does when a row names a company that is not in the
+ * workspace yet.
+ *
+ * `skip` imports the person and leaves the affiliation unlinked, reporting it as
+ * a row warning. `create` invents the company from the row's own domain and name
+ * so the position can be linked. Only the People import reads this; the other
+ * objects fail a missing company outright, per `import-export.md`.
+ */
+export const ON_MISSING_COMPANY = ['skip', 'create'] as const
+
 /**
  * `pending → validating → ready | failed → committing → completed | failed`.
  *
@@ -45,6 +56,7 @@ export const IMPORT_ROW_ACTIONS = ['pending', 'create', 'update', 'skip', 'error
 export type ImportSource = (typeof IMPORT_SOURCES)[number]
 export type ImportObject = (typeof IMPORT_OBJECTS)[number]
 export type ImportConflictMode = (typeof IMPORT_CONFLICT_MODES)[number]
+export type OnMissingCompany = (typeof ON_MISSING_COMPANY)[number]
 export type ImportJobStatus = (typeof IMPORT_JOB_STATUSES)[number]
 export type ImportRowAction = (typeof IMPORT_ROW_ACTIONS)[number]
 
@@ -82,6 +94,7 @@ export const SOURCE_LABELS: Readonly<Record<ImportSource, string>> = {
   custom: 'Custom CSV',
   hubspot: 'HubSpot CSV pack',
   salesforce: 'Salesforce CSV pack',
+  attio: 'Attio CSV pack',
 }
 
 export const CONFLICT_MODE_LABELS: Readonly<Record<ImportConflictMode, string>> = {
@@ -89,11 +102,25 @@ export const CONFLICT_MODE_LABELS: Readonly<Record<ImportConflictMode, string>>
   update: 'Update existing',
 }
 
+export const ON_MISSING_COMPANY_LABELS: Readonly<Record<OnMissingCompany, string>> = {
+  skip: 'Skip and report',
+  create: 'Create the company',
+}
+
 export interface CsvColumn {
   /** The Kelpie CSV header, and the key a `column_map` is keyed by. */
   readonly key: string
   readonly label: string
   readonly required: boolean
+  /**
+   * A column an import may map but an export never writes.
+   *
+   * The People affiliation columns are the only ones: a person can hold many
+   * positions, so a single company and title on the person row would be lossy on
+   * the way out. They map on the way in to drive a Position, and the export and
+   * template leave them out. See `headersFor`.
+   */
+  readonly importOnly?: boolean
 }
 
 /**
@@ -102,13 +129,15 @@ export interface CsvColumn {
  * Order is the header order of an export and of a template, so a file Kelpie
  * wrote maps onto itself by exact header match with no preset involved.
  *
- * Job title is absent from Person on purpose: it lives on Position, which is
- * what the contact title in a HubSpot or Salesforce export maps to.
+ * Job title is never stored on Person: it lives on Position. A People import may
+ * still carry `company_domain`, `company_name` and `title`, which drive a
+ * Position for the person rather than a field on them. Those three are
+ * `importOnly`, so an export and a template leave them out.
  */
 export const OBJECT_COLUMNS: Readonly<Record<ImportObject, readonly CsvColumn[]>> = {
   companies: [
     { key: 'name', label: 'Name', required: true },
-    { key: 'domain', label: 'Domain', required: true },
+    { key: 'domain', label: 'Domain', required: false },
     { key: 'industry', label: 'Industry', required: false },
     { key: 'stage', label: 'Stage', required: false },
     { key: 'size_band', label: 'Size band', required: false },
@@ -131,6 +160,9 @@ export const OBJECT_COLUMNS: Readonly<Record<ImportObject, readonly CsvColumn[]>
     { key: 'summary', label: 'Summary', required: false },
     { key: 'tags', label: 'Tags', required: false },
     { key: 'phones', label: 'Phones', required: false },
+    { key: 'company_domain', label: 'Company domain', required: false, importOnly: true },
+    { key: 'company_name', label: 'Company name', required: false, importOnly: true },
+    { key: 'title', label: 'Title', required: false, importOnly: true },
   ],
   positions: [
     { key: 'person_email', label: 'Person email', required: true },
@@ -262,6 +294,8 @@ export interface ImportJob extends RecordTimestamps {
   readonly object: ImportObject
   readonly status: ImportJobStatus
   readonly conflictMode: ImportConflictMode
+  /** What a People import does with a row naming an absent company. `skip` for every other object. */
+  readonly onMissingCompany: OnMissingCompany
   readonly matchKey: string
   readonly columnMap: ImportColumnMap
   /** The headers as they appeared in the uploaded file, in file order. */
@@ -270,6 +304,12 @@ export interface ImportJob extends RecordTimestamps {
   readonly counts: ImportCounts
   /** At most `IMPORT_REPORTED_ERRORS`. `counts.error` is the true number of failing rows. */
   readonly errors: readonly ImportRowError[]
+  /**
+   * Non-fatal notes about rows that were imported. A People row whose company is
+   * absent under `on_missing_company: skip` lands here: the person imported, the
+   * position did not. At most `IMPORT_REPORTED_ERRORS`.
+   */
+  readonly warnings: readonly ImportRowError[]
   readonly preview: readonly ImportPreviewRow[]
 }
 
@@ -305,12 +345,14 @@ export const importJobSchema: z.ZodType<ImportJob, unknown> = z
     object: z.enum(IMPORT_OBJECTS),
     status: z.enum(IMPORT_JOB_STATUSES),
     conflict_mode: z.enum(IMPORT_CONFLICT_MODES),
+    on_missing_company: z.enum(ON_MISSING_COMPANY),
     match_key: z.string(),
     column_map: z.record(z.string(), z.string().nullable()),
     source_headers: z.array(z.string()),
     file_name: z.string().nullable(),
     counts: countsSchema,
     errors: z.array(rowErrorSchema),
+    warnings: z.array(rowErrorSchema),
     preview: z.array(previewRowSchema),
     ...recordTimestamps,
   })
@@ -321,12 +363,14 @@ export const importJobSchema: z.ZodType<ImportJob, unknown> = z
       object: wire.object,
       status: wire.status,
       conflictMode: wire.conflict_mode,
+      onMissingCompany: wire.on_missing_company,
       matchKey: wire.match_key,
       columnMap: wire.column_map,
       sourceHeaders: wire.source_headers,
       fileName: wire.file_name,
       counts: wire.counts,
       errors: wire.errors,
+      warnings: wire.warnings,
       preview: wire.preview,
       createdAt: wire.created_at,
       updatedAt: wire.updated_at,

package/src/index.ts

@@ -46,6 +46,7 @@ export {
   PLAN_ITEM_STATUS_LABELS,
   PLAN_ITEM_STATUSES,
   PREFERRED_CHANNELS,
+  RECORD_TARGET_TYPE_LABELS,
   RECORD_TARGET_TYPES,
   RELATIONSHIP_LEVELS,
   ROLE_STATUS_LABELS,
@@ -149,6 +150,15 @@ export type {
 export { createNoteBody, noteBody, noteSchema } from './note.ts'
 export type { CreateNoteInput, Note, NoteInput } from './note.ts'
 
+export { createListBody, listBody, listSchema } from './list.ts'
+export type { CreateListInput, List, ListInput } from './list.ts'
+
+export { addListMemberBody, listMemberSchema } from './listMember.ts'
+export type { AddListMemberInput, ListMember } from './listMember.ts'
+
+export { listMembershipSchema } from './listMembership.ts'
+export type { ListMembership } from './listMembership.ts'
+
 export { createPlanItemBody, planItemBody, planItemSchema } from './planItem.ts'
 export type { CreatePlanItemInput, PlanItem, PlanItemInput } from './planItem.ts'
 
@@ -196,6 +206,8 @@ export {
   MAX_IMPORT_ROWS,
   OBJECT_COLUMNS,
   OBJECT_LABELS,
+  ON_MISSING_COMPANY,
+  ON_MISSING_COMPANY_LABELS,
   SOURCE_LABELS,
   SYNC_IMPORT_ROWS,
   defaultMatchKeyId,
@@ -217,6 +229,7 @@ export type {
   ImportRowError,
   ImportSource,
   MatchKeyOption,
+  OnMissingCompany,
   SettledRowAction,
 } from './importExport.ts'
 
@@ -288,6 +301,10 @@ export type { Member, UpdateMemberRoleInput } from './member.ts'
 
 export { moduleSettingSchema, updateModuleSettingBody } from './moduleSetting.ts'
 export type { ModuleSetting, UpdateModuleSettingInput } from './moduleSetting.ts'
+export { sampleDataCountsSchema } from './sampleData.ts'
+export type { SampleDataCounts } from './sampleData.ts'
+export { relinkEmailDomainsCountsSchema } from './emailDomainLinker.ts'
+export type { RelinkEmailDomainsCounts } from './emailDomainLinker.ts'
 
 export { mcpToolSchema } from './mcpTool.ts'
 export type { McpTool } from './mcpTool.ts'
@@ -326,6 +343,7 @@ export {
   accountSchema,
   accountSessionSchema,
   changePasswordBody,
+  listViewPreferenceSchema,
   updateAccountBody,
   updateAccountPreferencesBody,
 } from './account.ts'
@@ -334,6 +352,10 @@ export type {
   AccountPreferences,
   AccountSession,
   ChangePasswordInput,
+  ListViewPreference,
   UpdateAccountInput,
   UpdateAccountPreferencesInput,
 } from './account.ts'
+
+export { publicConfigSchema } from './publicConfig.ts'
+export type { PublicConfig, PublicRuntimeMode } from './publicConfig.ts'

package/src/list.ts

@@ -0,0 +1,73 @@
+import { z } from 'zod'
+
+import { RECORD_TARGET_TYPES } from './values.ts'
+import type { RecordTargetType } from './values.ts'
+import { definedFields, idSchema, recordTimestamps } from './wire.ts'
+import type { RecordTimestamps } from './wire.ts'
+
+/**
+ * Wire and write shapes for `/v1/lists`.
+ *
+ * A list holds records of one type. The type is chosen at creation and never
+ * changes; a member added to it must match, and the database rejects a mismatch
+ * with a composite foreign key rather than trusting the service to check.
+ *
+ * `memberCount` is a read-only rollup returned on list responses so an index
+ * page can render totals without a follow-up call per row.
+ */
+
+export interface List extends RecordTimestamps {
+  readonly id: string
+  readonly name: string
+  readonly description: string | null
+  readonly targetType: RecordTargetType
+  readonly memberCount: number
+}
+
+export const listSchema: z.ZodType<List, unknown> = z
+  .object({
+    id: idSchema,
+    name: z.string(),
+    description: z.string().nullable(),
+    target_type: z.enum(RECORD_TARGET_TYPES),
+    member_count: z.number().int().nonnegative(),
+    ...recordTimestamps,
+  })
+  .transform(
+    (wire): List => ({
+      id: wire.id,
+      name: wire.name,
+      description: wire.description,
+      targetType: wire.target_type,
+      memberCount: wire.member_count,
+      createdAt: wire.created_at,
+      updatedAt: wire.updated_at,
+    }),
+  )
+
+export interface CreateListInput {
+  readonly name: string
+  readonly targetType: RecordTargetType
+  readonly description?: string | null
+}
+
+export function createListBody(input: CreateListInput): Record<string, unknown> {
+  return definedFields({
+    name: input.name,
+    target_type: input.targetType,
+    description: input.description,
+  })
+}
+
+/** `targetType` is fixed for the life of a list, so it is not editable here. */
+export interface ListInput {
+  readonly name?: string
+  readonly description?: string | null
+}
+
+export function listBody(input: ListInput): Record<string, unknown> {
+  return definedFields({
+    name: input.name,
+    description: input.description,
+  })
+}

package/src/listMember.ts

@@ -0,0 +1,54 @@
+import { z } from 'zod'
+
+import { RECORD_TARGET_TYPES } from './values.ts'
+import type { RecordTargetType } from './values.ts'
+import { definedFields, idSchema, timestampSchema } from './wire.ts'
+
+/**
+ * Wire and write shapes for `/v1/lists/:id/members`.
+ *
+ * A membership carries no state of its own: adding or removing a record is the
+ * only edit. `targetName` is resolved server-side via `resolveTargetNames` so a
+ * heterogeneous members table can render without an N+1.
+ */
+
+export interface ListMember {
+  readonly id: string
+  readonly listId: string
+  readonly targetType: RecordTargetType
+  readonly targetId: string
+  readonly targetName: string | null
+  readonly addedAt: Date
+}
+
+export const listMemberSchema: z.ZodType<ListMember, unknown> = z
+  .object({
+    id: idSchema,
+    list_id: idSchema,
+    target_type: z.enum(RECORD_TARGET_TYPES),
+    target_id: idSchema,
+    target_name: z.string().nullable(),
+    added_at: timestampSchema,
+  })
+  .transform(
+    (wire): ListMember => ({
+      id: wire.id,
+      listId: wire.list_id,
+      targetType: wire.target_type,
+      targetId: wire.target_id,
+      targetName: wire.target_name,
+      addedAt: wire.added_at,
+    }),
+  )
+
+export interface AddListMemberInput {
+  readonly targetType: RecordTargetType
+  readonly targetId: string
+}
+
+export function addListMemberBody(input: AddListMemberInput): Record<string, unknown> {
+  return definedFields({
+    target_type: input.targetType,
+    target_id: input.targetId,
+  })
+}

package/src/listMembership.ts

@@ -0,0 +1,45 @@
+import { z } from 'zod'
+
+import { RECORD_TARGET_TYPES } from './values.ts'
+import type { RecordTargetType } from './values.ts'
+import { idSchema, timestampSchema } from './wire.ts'
+
+/**
+ * "Which lists is this record on?" — a membership joined with its list.
+ *
+ * Returned by `GET /v1/list-memberships?target_type=X&target_id=Y`. The joined
+ * list fields (`listName`, `listTargetType`) come along because a record's
+ * detail page wants to render its chips without a follow-up call per list.
+ */
+
+export interface ListMembership {
+  readonly id: string
+  readonly listId: string
+  readonly listName: string
+  readonly listTargetType: RecordTargetType
+  readonly targetType: RecordTargetType
+  readonly targetId: string
+  readonly addedAt: Date
+}
+
+export const listMembershipSchema: z.ZodType<ListMembership, unknown> = z
+  .object({
+    id: idSchema,
+    list_id: idSchema,
+    list_name: z.string(),
+    list_target_type: z.enum(RECORD_TARGET_TYPES),
+    target_type: z.enum(RECORD_TARGET_TYPES),
+    target_id: idSchema,
+    added_at: timestampSchema,
+  })
+  .transform(
+    (wire): ListMembership => ({
+      id: wire.id,
+      listId: wire.list_id,
+      listName: wire.list_name,
+      listTargetType: wire.list_target_type,
+      targetType: wire.target_type,
+      targetId: wire.target_id,
+      addedAt: wire.added_at,
+    }),
+  )

package/src/publicConfig.ts

@@ -0,0 +1,31 @@
+import { z } from 'zod'
+
+/**
+ * Wire shape for `GET /v1/public/config`.
+ *
+ * A public, credential-free endpoint the browser reads once at boot. It names
+ * which runtime the server is in, and the human-readable name of this
+ * deployment. The UI uses `runtimeMode` to gate a non-production banner and
+ * `siteName` to label it. Nothing here is sensitive: `runtimeMode` is
+ * observable from any error message, and `siteName` exists to be visible.
+ */
+
+export type PublicRuntimeMode = 'development' | 'test' | 'production'
+
+export interface PublicConfig {
+  readonly runtimeMode: PublicRuntimeMode
+  /** Undefined when the assembly did not set `KELPIE_SITE_NAME`. */
+  readonly siteName: string | null
+}
+
+export const publicConfigSchema = z
+  .strictObject({
+    runtime_mode: z.enum(['development', 'test', 'production']),
+    site_name: z.string().min(1).nullable(),
+  })
+  .transform(
+    (wire): PublicConfig => ({
+      runtimeMode: wire.runtime_mode,
+      siteName: wire.site_name,
+    }),
+  )

package/src/sampleData.ts

@@ -0,0 +1,52 @@
+import { z } from 'zod'
+
+/**
+ * Wire shape for `POST /v1/workspaces/:id/sample-data`.
+ *
+ * The endpoint takes no body. The response is a count per object type, so a
+ * caller can tell the reader what the button just did without a second query.
+ */
+
+export interface SampleDataCounts {
+  readonly companies: number
+  readonly people: number
+  readonly positions: number
+  readonly deals: number
+  readonly planItems: number
+  readonly notes: number
+  readonly opportunities: number
+  readonly raises: number
+  readonly partnerships: number
+  readonly roles: number
+  readonly candidates: number
+}
+
+export const sampleDataCountsSchema: z.ZodType<SampleDataCounts, unknown> = z
+  .object({
+    companies: z.number().int().nonnegative(),
+    people: z.number().int().nonnegative(),
+    positions: z.number().int().nonnegative(),
+    deals: z.number().int().nonnegative(),
+    plan_items: z.number().int().nonnegative(),
+    notes: z.number().int().nonnegative(),
+    opportunities: z.number().int().nonnegative(),
+    raises: z.number().int().nonnegative(),
+    partnerships: z.number().int().nonnegative(),
+    roles: z.number().int().nonnegative(),
+    candidates: z.number().int().nonnegative(),
+  })
+  .transform(
+    (wire): SampleDataCounts => ({
+      companies: wire.companies,
+      people: wire.people,
+      positions: wire.positions,
+      deals: wire.deals,
+      planItems: wire.plan_items,
+      notes: wire.notes,
+      opportunities: wire.opportunities,
+      raises: wire.raises,
+      partnerships: wire.partnerships,
+      roles: wire.roles,
+      candidates: wire.candidates,
+    }),
+  )

package/src/values.ts

@@ -115,6 +115,17 @@ export const RECORD_TARGET_TYPES = [
 
 export type RecordTargetType = (typeof RECORD_TARGET_TYPES)[number]
 
+/** Human labels for `RECORD_TARGET_TYPES`. Used by any picker that names a type. */
+export const RECORD_TARGET_TYPE_LABELS: Readonly<Record<RecordTargetType, string>> = {
+  person: 'Person',
+  company: 'Company',
+  deal: 'Deal',
+  opportunity: 'Opportunity',
+  partnership: 'Partnership',
+  raise: 'Raise',
+  candidate: 'Candidate',
+}
+
 /**
  * What `GET /v1/search` looks through, and the order its groups come back in.
  *