@kelpie/schemas 0.1.0

package/src/importExport.ts

@@ -0,0 +1,339 @@
+import { z } from 'zod'
+
+import { idSchema, recordTimestamps } from './wire.ts'
+import type { RecordTimestamps } from './wire.ts'
+
+/**
+ * Wire shapes and shared catalogues for `/v1/import` and `/v1/export`, per
+ * `import-export.md`.
+ *
+ * The column catalogue lives here rather than in the server module because both
+ * ends need it: the server validates a row against it, and the browser renders
+ * the mapping table from it. The source presets do not, so they stay server-side
+ * — 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_OBJECTS = ['companies', 'people', 'positions', 'deals'] as const
+export const IMPORT_CONFLICT_MODES = ['skip', 'update'] as const
+
+/**
+ * `pending → validating → ready | failed → committing → completed | failed`.
+ *
+ * `pending` is the moment between the row insert and the dry run starting. A
+ * synchronous job passes through it inside one request and is never observed
+ * there; an asynchronous one can be.
+ */
+export const IMPORT_JOB_STATUSES = [
+  'pending',
+  'validating',
+  'ready',
+  'committing',
+  'completed',
+  'failed',
+] as const
+
+/**
+ * What a dry run forecasts for a row, and what a commit records against it.
+ *
+ * `pending` is a row that has been stored but not yet planned, which is what
+ * every row of an asynchronous job is until its validation pass reaches it. The
+ * counts only ever hold the four settled actions.
+ */
+export const IMPORT_ROW_ACTIONS = ['pending', 'create', 'update', 'skip', 'error'] as const
+
+export type ImportSource = (typeof IMPORT_SOURCES)[number]
+export type ImportObject = (typeof IMPORT_OBJECTS)[number]
+export type ImportConflictMode = (typeof IMPORT_CONFLICT_MODES)[number]
+export type ImportJobStatus = (typeof IMPORT_JOB_STATUSES)[number]
+export type ImportRowAction = (typeof IMPORT_ROW_ACTIONS)[number]
+
+/** A row that has been planned. What a dry run and a commit both write back. */
+export type SettledRowAction = Exclude<ImportRowAction, 'pending'>
+
+/** Limits from `import-export.md`. Placeholders until billing exists. */
+export const MAX_IMPORT_FILE_BYTES = 10 * 1024 * 1024
+export const MAX_IMPORT_ROWS = 10_000
+
+/**
+ * Above this many rows a job validates and commits in the background, and the
+ * request answers `202` with the job in a transient status. The caller polls
+ * `GET /v1/import/jobs/{id}`.
+ */
+export const SYNC_IMPORT_ROWS = 500
+
+/** Mapped rows returned with a job, so a caller can check the mapping before committing. */
+export const IMPORT_PREVIEW_ROWS = 5
+
+/**
+ * Row errors carried on the job body. `counts.error` is the true total, so a
+ * truncated list is visible rather than mistaken for the whole story.
+ */
+export const IMPORT_REPORTED_ERRORS = 50
+
+export const OBJECT_LABELS: Readonly<Record<ImportObject, string>> = {
+  companies: 'Companies',
+  people: 'People',
+  positions: 'Positions',
+  deals: 'Deals',
+}
+
+export const SOURCE_LABELS: Readonly<Record<ImportSource, string>> = {
+  custom: 'Custom CSV',
+  hubspot: 'HubSpot CSV pack',
+  salesforce: 'Salesforce CSV pack',
+}
+
+export const CONFLICT_MODE_LABELS: Readonly<Record<ImportConflictMode, string>> = {
+  skip: 'Skip existing',
+  update: 'Update existing',
+}
+
+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
+}
+
+/**
+ * The canonical Kelpie CSV columns per object (`import-export.md`).
+ *
+ * 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.
+ */
+export const OBJECT_COLUMNS: Readonly<Record<ImportObject, readonly CsvColumn[]>> = {
+  companies: [
+    { key: 'name', label: 'Name', required: true },
+    { key: 'domain', label: 'Domain', required: true },
+    { key: 'industry', label: 'Industry', required: false },
+    { key: 'stage', label: 'Stage', required: false },
+    { key: 'size_band', label: 'Size band', required: false },
+    { key: 'account_type', label: 'Account type', required: false },
+    { key: 'icp_fit', label: 'ICP fit', required: false },
+    { key: 'description', label: 'Description', required: false },
+    { key: 'summary', label: 'Summary', required: false },
+    { key: 'tags', label: 'Tags', required: false },
+    { key: 'website', label: 'Website', required: false },
+    { key: 'hq', label: 'HQ', required: false },
+  ],
+  people: [
+    { key: 'name', label: 'Name', required: true },
+    { key: 'email', label: 'Email', required: true },
+    { key: 'timezone', label: 'Timezone', required: false },
+    { key: 'location', label: 'Location', required: false },
+    { key: 'preferred_channel', label: 'Preferred channel', required: false },
+    { key: 'influence', label: 'Influence', required: false },
+    { key: 'relationship', label: 'Relationship', required: false },
+    { key: 'summary', label: 'Summary', required: false },
+    { key: 'tags', label: 'Tags', required: false },
+    { key: 'phones', label: 'Phones', required: false },
+  ],
+  positions: [
+    { key: 'person_email', label: 'Person email', required: true },
+    { key: 'company_domain', label: 'Company domain', required: true },
+    { key: 'title', label: 'Title', required: true },
+  ],
+  deals: [
+    { key: 'name', label: 'Name', required: true },
+    { key: 'company_domain', label: 'Company domain', required: true },
+    { key: 'stage', label: 'Stage', required: true },
+    { key: 'value', label: 'Value', required: true },
+    { key: 'owner_email', label: 'Owner email', required: false },
+    { key: 'expected_close', label: 'Expected close', required: false },
+    { key: 'person_emails', label: 'Person emails', required: false },
+    { key: 'competitors', label: 'Competitors', required: false },
+    { key: 'risks', label: 'Risks', required: false },
+    { key: 'why_win', label: 'Why we win', required: false },
+    { key: 'summary', label: 'Summary', required: false },
+    { key: 'tags', label: 'Tags', required: false },
+    { key: 'external_id', label: 'External id', required: false },
+  ],
+}
+
+/** Columns whose value is a pipe-separated list (`a|b|c`), per `import-export.md`. */
+export const LIST_COLUMNS: ReadonlySet<string> = new Set([
+  'tags',
+  'phones',
+  'competitors',
+  'person_emails',
+  'tech_stack',
+])
+
+export interface MatchKeyOption {
+  /** The `match_key` a request sends. Composite keys join their columns with `|`. */
+  readonly id: string
+  readonly label: string
+  /** Kelpie columns the key is built from. Every one must be mapped and non-empty. */
+  readonly columns: readonly string[]
+}
+
+/** Selectable match keys per object. The first of each list is the default. */
+export const MATCH_KEYS: Readonly<Record<ImportObject, readonly MatchKeyOption[]>> = {
+  companies: [
+    { id: 'domain', label: 'domain', columns: ['domain'] },
+    { id: 'name', label: 'name', columns: ['name'] },
+  ],
+  people: [{ id: 'email', label: 'email', columns: ['email'] }],
+  positions: [
+    {
+      id: 'person_email|company_domain|title',
+      label: 'person_email + company_domain + title',
+      columns: ['person_email', 'company_domain', 'title'],
+    },
+    {
+      id: 'person_email|company_domain',
+      label: 'person_email + company_domain',
+      columns: ['person_email', 'company_domain'],
+    },
+  ],
+  deals: [
+    { id: 'external_id', label: 'external_id', columns: ['external_id'] },
+    {
+      id: 'name|company_domain',
+      label: 'name + company_domain',
+      columns: ['name', 'company_domain'],
+    },
+  ],
+}
+
+export function defaultMatchKeyId(object: ImportObject): string {
+  const [first] = MATCH_KEYS[object]
+
+  if (first === undefined) {
+    throw new Error(`No match keys declared for ${object}`)
+  }
+
+  return first.id
+}
+
+/** @returns The named key, or undefined when no such key exists for this object. */
+export function findMatchKey(object: ImportObject, matchKeyId: string): MatchKeyOption | undefined {
+  return MATCH_KEYS[object].find((key) => key.id === matchKeyId)
+}
+
+/**
+ * Kelpie columns a job must have mapped: the object's required ones plus every
+ * column the chosen match key is built from.
+ */
+export function requiredColumns(object: ImportObject, matchKey: MatchKeyOption): readonly string[] {
+  const required = OBJECT_COLUMNS[object].filter((column) => column.required).map((c) => c.key)
+
+  return [...new Set([...required, ...matchKey.columns])]
+}
+
+export interface ImportRowError {
+  /** The line in the file, counting the header as line 1. */
+  readonly row: number
+  readonly field: string
+  readonly message: string
+}
+
+export interface ImportCounts {
+  readonly total: number
+  readonly create: number
+  readonly update: number
+  readonly skip: number
+  readonly error: number
+}
+
+/** A mapped row as Kelpie read it, for checking a column map before committing. */
+export interface ImportPreviewRow {
+  readonly row: number
+  readonly action: ImportRowAction
+  /** Kelpie column → value, for the mapped columns only. */
+  readonly values: Readonly<Record<string, string>>
+}
+
+/**
+ * A `column_map`: Kelpie column → source header, or null to ignore the column.
+ *
+ * A key absent from the map means the same as null. Both are the ordinary way to
+ * say a file has no such column.
+ */
+export type ImportColumnMap = Readonly<Record<string, string | null>>
+
+export interface ImportJob extends RecordTimestamps {
+  readonly id: string
+  readonly source: ImportSource
+  readonly object: ImportObject
+  readonly status: ImportJobStatus
+  readonly conflictMode: ImportConflictMode
+  readonly matchKey: string
+  readonly columnMap: ImportColumnMap
+  /** The headers as they appeared in the uploaded file, in file order. */
+  readonly sourceHeaders: readonly string[]
+  readonly fileName: string | null
+  readonly counts: ImportCounts
+  /** At most `IMPORT_REPORTED_ERRORS`. `counts.error` is the true number of failing rows. */
+  readonly errors: readonly ImportRowError[]
+  readonly preview: readonly ImportPreviewRow[]
+}
+
+const countsSchema = z.object({
+  total: z.number().int(),
+  create: z.number().int(),
+  update: z.number().int(),
+  skip: z.number().int(),
+  error: z.number().int(),
+})
+
+const rowErrorSchema = z.object({
+  row: z.number().int(),
+  field: z.string(),
+  message: z.string(),
+})
+
+const previewRowSchema = z.object({
+  row: z.number().int(),
+  action: z.enum(IMPORT_ROW_ACTIONS),
+  values: z.record(z.string(), z.string()),
+})
+
+/**
+ * `workspace_id` is not on this body, unlike the sample in `import-export.md`.
+ * `api.md` makes the workspace implicit on every endpoint and no other resource
+ * returns it; one that did would be the odd one out for no gain.
+ */
+export const importJobSchema: z.ZodType<ImportJob, unknown> = z
+  .object({
+    id: idSchema,
+    source: z.enum(IMPORT_SOURCES),
+    object: z.enum(IMPORT_OBJECTS),
+    status: z.enum(IMPORT_JOB_STATUSES),
+    conflict_mode: z.enum(IMPORT_CONFLICT_MODES),
+    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),
+    preview: z.array(previewRowSchema),
+    ...recordTimestamps,
+  })
+  .transform(
+    (wire): ImportJob => ({
+      id: wire.id,
+      source: wire.source,
+      object: wire.object,
+      status: wire.status,
+      conflictMode: wire.conflict_mode,
+      matchKey: wire.match_key,
+      columnMap: wire.column_map,
+      sourceHeaders: wire.source_headers,
+      fileName: wire.file_name,
+      counts: wire.counts,
+      errors: wire.errors,
+      preview: wire.preview,
+      createdAt: wire.created_at,
+      updatedAt: wire.updated_at,
+    }),
+  )
+
+/** Statuses a job will not move on from without another request. */
+export function isImportJobSettled(status: ImportJobStatus): boolean {
+  return status === 'ready' || status === 'completed' || status === 'failed'
+}

package/src/index.ts

@@ -0,0 +1,324 @@
+/**
+ * `@kelpie/schemas` — the wire contract for `/v1`, as Zod schemas.
+ *
+ * Roadmap decision 8: the UI decodes API responses with Zod, and a schema's
+ * `.parse` is already the `Decoder<T>` the API client takes. These schemas live
+ * in their own package because `@kelpie/ui` must not import `@kelpie/server`;
+ * that would put Drizzle, postgres.js, and Node built-ins in the browser bundle.
+ * The dependency list here is Zod and nothing else, which is also what makes the
+ * package usable from the cloud repo.
+ *
+ * Each resource module holds three things: the record the UI works with, a
+ * schema that parses the `snake_case` response into it, and a function that
+ * builds a request body back out of it.
+ */
+
+export {
+  ACCOUNT_TYPES,
+  ACTIVITY_KINDS,
+  AGENT_RUN_STATUS_LABELS,
+  AGENT_RUN_STATUSES,
+  AGENT_TASK_PLACEMENTS,
+  AGENT_TASK_TARGET_TYPES,
+  CANDIDATE_STATUS_LABELS,
+  CANDIDATE_STATUSES,
+  COMPANY_STAGES,
+  EXTENSIBLE_RECORD_TYPES,
+  FIRST_INTERVIEW_STAGE,
+  FORM_FIELD_MAP_TARGET_LABELS,
+  FORM_FIELD_MAP_TARGETS,
+  FORM_FIELD_TYPES,
+  FORM_OPTION_VALUE_TYPES,
+  FORM_STATUSES,
+  ICP_FITS,
+  IN_PROCESS,
+  INFLUENCE_LEVELS,
+  INTERVIEW_STAGE_LABELS,
+  INTERVIEW_STAGES,
+  INVITABLE_ROLES,
+  INVITE_STATUSES,
+  MEMBER_ROLES,
+  OPEN_PLAN_ITEM_STATUSES,
+  PERSON_EMAIL_TARGET,
+  PIPELINE_KIND_LABELS,
+  PIPELINE_KINDS,
+  PLAN_ITEM_STATUS_LABELS,
+  PLAN_ITEM_STATUSES,
+  PREFERRED_CHANNELS,
+  RECORD_TARGET_TYPES,
+  RELATIONSHIP_LEVELS,
+  ROLE_STATUS_LABELS,
+  ROLE_STATUSES,
+  SEARCH_COLLECTIONS,
+  SIZE_BANDS,
+  SOCIAL_NETWORK_IDS,
+  SOCIAL_NETWORK_LABELS,
+  THEME_PREFERENCES,
+  WEBHOOK_DELIVERY_STATUSES,
+  WEBHOOK_EVENTS,
+  WEBHOOK_SETTABLE_STATUSES,
+  WEBHOOK_STATUS_LABELS,
+  WEBHOOK_STATUSES,
+} from './values.ts'
+export type {
+  AccountType,
+  ActivityKind,
+  AgentRunStatus,
+  AgentTaskPlacement,
+  AgentTaskTargetType,
+  CandidateStatus,
+  CompanyStage,
+  ExtensibleRecordType,
+  FormFieldMapTarget,
+  FormFieldType,
+  FormOptionValueType,
+  FormStatus,
+  IcpFit,
+  Influence,
+  InterviewStage,
+  InvitableRole,
+  InviteStatus,
+  MemberRole,
+  PipelineKind,
+  PlanItemStatus,
+  PreferredChannel,
+  RecordTargetType,
+  Relationship,
+  RoleStatus,
+  SearchCollection,
+  SizeBand,
+  SocialNetworkId,
+  ThemePreference,
+  WebhookDeliveryStatus,
+  WebhookEvent,
+  WebhookSettableStatus,
+  WebhookStatus,
+} from './values.ts'
+
+export { definedFields, idSchema, nullableTimestampSchema, timestampSchema } from './wire.ts'
+export type { RecordTimestamps } from './wire.ts'
+
+export { personBody, personSchema } from './person.ts'
+export type { Person, PersonInput, SocialProfile } from './person.ts'
+
+export { companyBody, companySchema } from './company.ts'
+export type { Company, CompanyInput } from './company.ts'
+
+export { createPositionBody, positionSchema, updatePositionBody } from './position.ts'
+export type { CreatePositionInput, Position } from './position.ts'
+
+export { dealBody, dealSchema } from './deal.ts'
+export type { Deal, DealInput } from './deal.ts'
+
+export { opportunityBody, opportunitySchema } from './opportunity.ts'
+export type { Opportunity, OpportunityInput } from './opportunity.ts'
+
+export { partnershipBody, partnershipSchema } from './partnership.ts'
+export type { Partnership, PartnershipInput } from './partnership.ts'
+
+export { raiseBody, raiseSchema } from './raise.ts'
+export type { Raise, RaiseInput } from './raise.ts'
+
+export { roleBody, roleSchema } from './role.ts'
+export type { Role, RoleInput } from './role.ts'
+
+export { candidateBody, candidateSchema, createCandidateBody } from './candidate.ts'
+export type { Candidate, CandidateInput, CreateCandidateInput } from './candidate.ts'
+
+export {
+  createPipelineStageBody,
+  pipelineStageSchema,
+  updatePipelineStageBody,
+} from './pipelineStage.ts'
+export type {
+  CreatePipelineStageInput,
+  PipelineStage,
+  UpdatePipelineStageInput,
+} from './pipelineStage.ts'
+
+export { createNoteBody, noteBody, noteSchema } from './note.ts'
+export type { CreateNoteInput, Note, NoteInput } from './note.ts'
+
+export { createPlanItemBody, planItemBody, planItemSchema } from './planItem.ts'
+export type { CreatePlanItemInput, PlanItem, PlanItemInput } from './planItem.ts'
+
+export { createDecisionBody, decisionBody, decisionSchema } from './decision.ts'
+export type { CreateDecisionInput, Decision, DecisionInput } from './decision.ts'
+
+export {
+  MAX_HANDBOOK_DEPTH,
+  createHandbookPageBody,
+  handbookPageBody,
+  handbookPageSchema,
+} from './handbookPage.ts'
+export type {
+  CreateHandbookPageInput,
+  HandbookPage,
+  HandbookPageInput,
+} from './handbookPage.ts'
+
+export { createFormBody, formBody, formSchema } from './form.ts'
+export type {
+  CreateFormInput,
+  Form,
+  FormField,
+  FormFieldInput,
+  FormFieldOption,
+  FormFieldOptionInput,
+  FormInput,
+} from './form.ts'
+
+export { formSubmissionSchema, formSubmitResultSchema } from './formSubmission.ts'
+export type { FormSubmission, FormSubmitResult } from './formSubmission.ts'
+
+export {
+  CONFLICT_MODE_LABELS,
+  IMPORT_CONFLICT_MODES,
+  IMPORT_JOB_STATUSES,
+  IMPORT_OBJECTS,
+  IMPORT_PREVIEW_ROWS,
+  IMPORT_REPORTED_ERRORS,
+  IMPORT_ROW_ACTIONS,
+  IMPORT_SOURCES,
+  LIST_COLUMNS,
+  MATCH_KEYS,
+  MAX_IMPORT_FILE_BYTES,
+  MAX_IMPORT_ROWS,
+  OBJECT_COLUMNS,
+  OBJECT_LABELS,
+  SOURCE_LABELS,
+  SYNC_IMPORT_ROWS,
+  defaultMatchKeyId,
+  findMatchKey,
+  importJobSchema,
+  isImportJobSettled,
+  requiredColumns,
+} from './importExport.ts'
+export type {
+  CsvColumn,
+  ImportColumnMap,
+  ImportConflictMode,
+  ImportCounts,
+  ImportJob,
+  ImportJobStatus,
+  ImportObject,
+  ImportPreviewRow,
+  ImportRowAction,
+  ImportRowError,
+  ImportSource,
+  MatchKeyOption,
+  SettledRowAction,
+} from './importExport.ts'
+
+export {
+  WEBHOOK_SECRET_OVERLAP_HOURS,
+  createWebhookBody,
+  createdWebhookSchema,
+  rotateWebhookSecretBody,
+  webhookBody,
+  webhookDeliverySchema,
+  webhookSchema,
+} from './webhook.ts'
+export type {
+  CreateWebhookInput,
+  CreatedWebhook,
+  RotateWebhookSecretInput,
+  Webhook,
+  WebhookDelivery,
+  WebhookInput,
+} from './webhook.ts'
+
+export {
+  agentRunSchema,
+  agentTaskDefinitionSchema,
+  createRegisteredAgentBody,
+  registeredAgentBody,
+  registeredAgentSchema,
+  resolveAgentTaskBody,
+  resolvedAgentTaskSchema,
+  runAgentTaskBody,
+} from './agentTask.ts'
+export type {
+  AgentRun,
+  AgentTaskContextPack,
+  AgentTaskDefinition,
+  CreateRegisteredAgentInput,
+  RegisteredAgent,
+  RegisteredAgentInput,
+  ResolveAgentTaskInput,
+  ResolvedAgentTask,
+  RunAgentTaskInput,
+} from './agentTask.ts'
+
+export { activitySchema } from './activity.ts'
+export type { Activity } from './activity.ts'
+
+export { dashboardSchema } from './dashboard.ts'
+export type {
+  Dashboard,
+  DashboardActivity,
+  DashboardDecision,
+  DashboardNote,
+  DashboardPipeline,
+  DashboardPlanItem,
+  DashboardSignal,
+  DashboardStaleContact,
+  DashboardTouchpoint,
+  TargetRef,
+} from './dashboard.ts'
+
+export { searchResultsSchema } from './search.ts'
+export type { SearchResult, SearchResultGroup, SearchResults } from './search.ts'
+
+export { memberSchema, updateMemberRoleBody } from './member.ts'
+export type { Member, UpdateMemberRoleInput } from './member.ts'
+
+export { moduleSettingSchema, updateModuleSettingBody } from './moduleSetting.ts'
+export type { ModuleSetting, UpdateModuleSettingInput } from './moduleSetting.ts'
+
+export { mcpToolSchema } from './mcpTool.ts'
+export type { McpTool } from './mcpTool.ts'
+
+export { createInviteBody, inviteSchema, resendInviteBody } from './invite.ts'
+export type { CreateInviteInput, Invite, ResendInviteInput } from './invite.ts'
+
+export {
+  confirmPasswordResetBody,
+  createWorkspaceBody,
+  logInBody,
+  requestPasswordResetBody,
+  sessionSchema,
+  signUpBody,
+  signedInAccountSchema,
+  updateWorkspaceBody,
+  workspaceSchema,
+} from './session.ts'
+export type {
+  ConfirmPasswordResetInput,
+  CreateWorkspaceInput,
+  LogInInput,
+  RequestPasswordResetInput,
+  Session,
+  SignUpInput,
+  SignedInAccount,
+  UpdateWorkspaceInput,
+  Workspace,
+} from './session.ts'
+
+export {
+  MINIMUM_PASSWORD_LENGTH,
+  accountPreferencesSchema,
+  accountSchema,
+  accountSessionSchema,
+  changePasswordBody,
+  updateAccountBody,
+  updateAccountPreferencesBody,
+} from './account.ts'
+export type {
+  Account,
+  AccountPreferences,
+  AccountSession,
+  ChangePasswordInput,
+  UpdateAccountInput,
+  UpdateAccountPreferencesInput,
+} from './account.ts'