@kelpie/schemas 0.10.0 → 0.12.0

package/src/importExport.ts

@@ -1,5 +1,6 @@
 import { z } from 'zod'
 
+import type { CustomFieldObjectType, PipelineKind } from './values.ts'
 import { idSchema, recordTimestamps } from './wire.ts'
 import type { RecordTimestamps } from './wire.ts'
 
@@ -14,7 +15,17 @@ import type { RecordTimestamps } from './wire.ts'
  */
 
 export const IMPORT_SOURCES = ['custom', 'hubspot', 'salesforce', 'attio'] as const
-export const IMPORT_OBJECTS = ['companies', 'people', 'positions', 'deals'] as const
+export const IMPORT_OBJECTS = [
+  'companies',
+  'people',
+  'positions',
+  'deals',
+  'opportunities',
+  'enquiries',
+  'partnerships',
+  'raises',
+  'custom_fields',
+] as const
 export const IMPORT_CONFLICT_MODES = ['skip', 'update'] as const
 
 /**
@@ -88,6 +99,11 @@ export const OBJECT_LABELS: Readonly<Record<ImportObject, string>> = {
   people: 'People',
   positions: 'Positions',
   deals: 'Deals',
+  opportunities: 'Opportunities',
+  enquiries: 'Enquiries',
+  partnerships: 'Partnerships',
+  raises: 'Fundraising',
+  custom_fields: 'Custom fields',
 }
 
 export const SOURCE_LABELS: Readonly<Record<ImportSource, string>> = {
@@ -215,6 +231,125 @@ export const OBJECT_COLUMNS: Readonly<Record<ImportObject, readonly CsvColumn[]>
     { key: 'tags', label: 'Tags', required: false },
     { key: 'external_id', label: 'External id', required: false },
   ],
+  opportunities: [
+    { key: 'name', label: 'Name', required: true },
+    { key: 'kind', label: 'Kind', required: true },
+    { key: 'company_domain', label: 'Company domain', required: false },
+    { key: 'stage', label: 'Stage', 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: 'summary', label: 'Summary', required: false },
+    { key: 'tags', label: 'Tags', required: false },
+  ],
+  enquiries: [
+    { key: 'name', label: 'Name', required: true },
+    { key: 'source', label: 'Source', required: false },
+    { key: 'company_domain', label: 'Company domain', required: false },
+    { key: 'stage', label: 'Stage', required: true },
+    { key: 'owner_email', label: 'Owner email', required: false },
+    { key: 'person_emails', label: 'Person emails', required: false },
+    { key: 'summary', label: 'Summary', required: false },
+    { key: 'tags', label: 'Tags', required: false },
+  ],
+  partnerships: [
+    { key: 'name', label: 'Name', required: true },
+    { key: 'company_domain', label: 'Company domain', required: true },
+    { key: 'stage', label: 'Stage', required: true },
+    { key: 'kind', label: 'Kind', required: true },
+    { key: 'next_touchpoint', label: 'Next touchpoint', required: false },
+    { key: 'owner_email', label: 'Owner email', required: false },
+    { key: 'goals', label: 'Goals', required: false },
+    { key: 'success_looks_like', label: 'Success looks like', required: false },
+    { key: 'person_emails', label: 'Person emails', required: false },
+    { key: 'summary', label: 'Summary', required: false },
+    { key: 'tags', label: 'Tags', required: false },
+  ],
+  raises: [
+    { key: 'name', label: 'Name', required: true },
+    { key: 'company_domain', label: 'Company domain', required: true },
+    { key: 'stage', label: 'Stage', required: true },
+    { key: 'check_size', label: 'Check size', required: false },
+    { key: 'currency', label: 'Currency', required: false },
+    { key: 'thesis_fit', label: 'Thesis fit', required: false },
+    { key: 'pass_reason', label: 'Pass reason', required: false },
+    { 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: 'summary', label: 'Summary', required: false },
+    { key: 'tags', label: 'Tags', required: false },
+  ],
+  custom_fields: [
+    { key: 'object_type', label: 'Object type', required: true },
+    { key: 'key', label: 'Key', required: true },
+    { key: 'label', label: 'Label', required: true },
+    { key: 'type', label: 'Type', required: true },
+    { key: 'options', label: 'Options', required: false },
+    { key: 'description', label: 'Description', required: false },
+    { key: 'sort_order', label: 'Sort order', required: true },
+  ],
+}
+
+/** Every object `GET /v1/export/{object}.csv` and the import wizard accept. */
+export const EXPORT_OBJECTS = IMPORT_OBJECTS
+
+export type ExportObject = ImportObject
+
+export function isImportObject(object: string): object is ImportObject {
+  return (IMPORT_OBJECTS as readonly string[]).includes(object)
+}
+
+/** @deprecated Use `OBJECT_LABELS`. Kept for callers that still import this name. */
+export const EXPORT_OBJECT_LABELS: Readonly<Record<ExportObject, string>> = OBJECT_LABELS
+
+/** Record exports that carry workspace custom field values as extra columns. */
+export function customFieldObjectTypeForExport(object: ExportObject): CustomFieldObjectType | null {
+  switch (object) {
+    case 'companies':
+      return 'company'
+    case 'people':
+      return 'person'
+    case 'deals':
+      return 'deal'
+    case 'opportunities':
+      return 'opportunity'
+    case 'enquiries':
+      return 'enquiry'
+    case 'partnerships':
+      return 'partnership'
+    case 'raises':
+      return 'raise'
+    default:
+      return null
+  }
+}
+
+/** The pipeline kind whose stages a row's `stage` column resolves against. */
+export function pipelineKindForImport(object: ImportObject): PipelineKind | null {
+  switch (object) {
+    case 'deals':
+      return 'deal'
+    case 'opportunities':
+      return 'opportunity'
+    case 'enquiries':
+      return 'enquiry'
+    case 'partnerships':
+      return 'partnership'
+    case 'raises':
+      return 'raise'
+    default:
+      return null
+  }
+}
+
+/** Kelpie column keys a job may map, including workspace custom field definition keys. */
+export function knownImportColumnKeys(
+  object: ImportObject,
+  customFieldKeys: readonly string[] = [],
+): readonly string[] {
+  const base = OBJECT_COLUMNS[object].map((column) => column.key)
+
+  return [...new Set([...base, ...customFieldKeys])]
 }
 
 /** Columns whose value is a pipe-separated list (`a|b|c`), per `import-export.md`. */
@@ -224,6 +359,7 @@ export const LIST_COLUMNS: ReadonlySet<string> = new Set([
   'competitors',
   'person_emails',
   'tech_stack',
+  'options',
 ])
 
 export interface MatchKeyOption {
@@ -261,6 +397,43 @@ export const MATCH_KEYS: Readonly<Record<ImportObject, readonly MatchKeyOption[]
       columns: ['name', 'company_domain'],
     },
   ],
+  opportunities: [
+    {
+      id: 'name|company_domain',
+      label: 'name + company_domain',
+      columns: ['name', 'company_domain'],
+    },
+    { id: 'name', label: 'name', columns: ['name'] },
+  ],
+  enquiries: [
+    {
+      id: 'name|company_domain',
+      label: 'name + company_domain',
+      columns: ['name', 'company_domain'],
+    },
+    { id: 'name', label: 'name', columns: ['name'] },
+  ],
+  partnerships: [
+    {
+      id: 'name|company_domain',
+      label: 'name + company_domain',
+      columns: ['name', 'company_domain'],
+    },
+  ],
+  raises: [
+    {
+      id: 'name|company_domain',
+      label: 'name + company_domain',
+      columns: ['name', 'company_domain'],
+    },
+  ],
+  custom_fields: [
+    {
+      id: 'object_type|key',
+      label: 'object_type + key',
+      columns: ['object_type', 'key'],
+    },
+  ],
 }
 
 export function defaultMatchKeyId(object: ImportObject): string {

package/src/index.ts

@@ -173,6 +173,17 @@ export type { Company, CompanyInput } from './company.ts'
 export { createPositionBody, positionSchema, updatePositionBody } from './position.ts'
 export type { CreatePositionInput, Position } from './position.ts'
 
+export {
+  convertEnquiryBody,
+  convertPipelineRecordBody,
+  convertPipelineRecordRequest,
+  convertedToForWire,
+  convertedToResponse,
+  convertedToSchema,
+  convertedToWireSchema,
+} from './conversion.ts'
+export type { ConvertedTo, ConvertPipelineRecordInput } from './conversion.ts'
+
 export { dealBody, dealSchema } from './deal.ts'
 export type { Deal, DealInput } from './deal.ts'
 
@@ -247,6 +258,32 @@ export type {
   FormInput,
 } from './form.ts'
 
+export {
+  FORM_MAP_OBJECT_TYPES,
+  FORM_MAP_OBJECT_TYPE_LABELS,
+  FORM_STANDARD_MAP_FIELDS,
+  buildCustomMapTarget,
+  buildCustomMapTargetEntry,
+  isCompatibleFormFieldType,
+  isKnownMapTarget,
+  isRepeatableMapTarget,
+  labelForMapTarget,
+  listMapTargetEntries,
+  listStandardMapTargetEntries,
+  metaForMapTargetEntry,
+  parseFormMapTarget,
+  resolveMapTargetEntry,
+  suggestedFormFieldType,
+} from './formMapTargets.ts'
+export type {
+  CustomFieldDefinitionRef,
+  FormMapObjectType,
+  FormMapStandardField,
+  FormMapTargetEntry,
+  FormMapValueType,
+  ParsedFormMapTarget,
+} from './formMapTargets.ts'
+
 export {
   FORM_SUBMISSION_LINK_TARGETS,
   formSubmissionSchema,
@@ -261,6 +298,8 @@ export type {
 
 export {
   CONFLICT_MODE_LABELS,
+  EXPORT_OBJECT_LABELS,
+  EXPORT_OBJECTS,
   IMPORT_CONFLICT_MODES,
   IMPORT_JOB_STATUSES,
   IMPORT_OBJECTS,
@@ -278,14 +317,19 @@ export {
   ON_MISSING_COMPANY_LABELS,
   SOURCE_LABELS,
   SYNC_IMPORT_ROWS,
+  customFieldObjectTypeForExport,
   defaultMatchKeyId,
   findMatchKey,
   importJobSchema,
   isImportJobSettled,
+  isImportObject,
+  knownImportColumnKeys,
+  pipelineKindForImport,
   requiredColumns,
 } from './importExport.ts'
 export type {
   CsvColumn,
+  ExportObject,
   ImportColumnMap,
   ImportConflictMode,
   ImportCounts,
@@ -321,6 +365,23 @@ export type {
 
 export { apiKeySchema, createApiKeyBody, createdApiKeySchema } from './apiKey.ts'
 export type { ApiKey, CreateApiKeyInput, CreatedApiKey } from './apiKey.ts'
+export {
+  API_KEY_ADMIN_RESOURCES,
+  API_KEY_GRANULAR_SCOPES,
+  API_KEY_OBJECT_CONFIG_RESOURCES,
+  API_KEY_OBJECT_DATA_RESOURCES,
+  API_KEY_OBJECT_READ_ONLY_RESOURCES,
+  API_KEY_PRESET_SCOPES,
+  API_KEY_SCOPE_GROUPS,
+  API_KEY_SCOPE_LABELS,
+  API_KEY_SCOPES,
+  dedupeApiKeyScopes,
+  expandApiKeyScopes,
+  isApiKeyGranularScope,
+  isApiKeyPresetScope,
+  satisfiesApiKeyScope,
+} from './apiKeyScopes.ts'
+export type { ApiKeyGranularScope, ApiKeyPresetScope, ApiKeyScope } from './apiKeyScopes.ts'
 
 export {
   agentRunSchema,

package/src/list.ts

@@ -22,13 +22,6 @@ export interface List extends RecordTimestamps {
   readonly description: string | null
   readonly targetType: RecordTargetType
   readonly memberCount: number
-  /**
-   * The consent purpose captured when a form submit adds a person to this
-   * list. Person lists only. Manual and API list adds capture nothing.
-   */
-  readonly consentPurposeId: string | null
-  /** The named purpose's slug, denormalised so a reader needs no second call. */
-  readonly consentPurposeSlug: string | null
 }
 
 export const listSchema: z.ZodType<List, unknown> = z
@@ -38,8 +31,6 @@ export const listSchema: z.ZodType<List, unknown> = z
     description: z.string().nullable(),
     target_type: z.enum(RECORD_TARGET_TYPES),
     member_count: z.number().int().nonnegative(),
-    consent_purpose_id: idSchema.nullable(),
-    consent_purpose_slug: z.string().nullable(),
     ...recordTimestamps,
   })
   .transform(
@@ -49,8 +40,6 @@ export const listSchema: z.ZodType<List, unknown> = z
       description: wire.description,
       targetType: wire.target_type,
       memberCount: wire.member_count,
-      consentPurposeId: wire.consent_purpose_id,
-      consentPurposeSlug: wire.consent_purpose_slug,
       createdAt: wire.created_at,
       updatedAt: wire.updated_at,
     }),
@@ -60,8 +49,6 @@ export interface CreateListInput {
   readonly name: string
   readonly targetType: RecordTargetType
   readonly description?: string | null
-  /** Person lists only. `null` on a company list is fine; a non-null value is `422`. */
-  readonly consentPurposeId?: string | null
 }
 
 export function createListBody(input: CreateListInput): Record<string, unknown> {
@@ -69,7 +56,6 @@ export function createListBody(input: CreateListInput): Record<string, unknown>
     name: input.name,
     target_type: input.targetType,
     description: input.description,
-    consent_purpose_id: input.consentPurposeId,
   })
 }
 
@@ -77,13 +63,11 @@ export function createListBody(input: CreateListInput): Record<string, unknown>
 export interface ListInput {
   readonly name?: string
   readonly description?: string | null
-  readonly consentPurposeId?: string | null
 }
 
 export function listBody(input: ListInput): Record<string, unknown> {
   return definedFields({
     name: input.name,
     description: input.description,
-    consent_purpose_id: input.consentPurposeId,
   })
 }

package/src/opportunity.ts

@@ -1,5 +1,7 @@
 import { z } from 'zod'
 
+import { convertedToWireSchema } from './conversion.ts'
+import type { ConvertedTo } from './conversion.ts'
 import { customFieldValuesBody, customFieldValuesSchema } from './customField.ts'
 import type { CustomFieldValue, CustomFieldValues } from './customField.ts'
 import { definedFields, idSchema, recordTimestamps } from './wire.ts'
@@ -21,6 +23,8 @@ export interface Opportunity extends RecordTimestamps {
   readonly personIds: readonly string[]
   readonly summary: string
   readonly tags: readonly string[]
+  /** Non-null once this record has been converted to another pipeline type. */
+  readonly convertedTo: ConvertedTo | null
   /** Workspace-defined fields, keyed by definition key. Always present (default `{}`). */
   readonly customFields: CustomFieldValues
 }
@@ -37,6 +41,7 @@ export const opportunitySchema: z.ZodType<Opportunity, unknown> = z
     person_ids: z.array(idSchema),
     summary: z.string(),
     tags: z.array(z.string()),
+    converted_to: convertedToWireSchema,
     custom_fields: customFieldValuesSchema,
     ...recordTimestamps,
   })
@@ -52,6 +57,10 @@ export const opportunitySchema: z.ZodType<Opportunity, unknown> = z
       personIds: wire.person_ids,
       summary: wire.summary,
       tags: wire.tags,
+      convertedTo:
+        wire.converted_to === null
+          ? null
+          : { targetType: wire.converted_to.target_type, targetId: wire.converted_to.target_id },
       customFields: wire.custom_fields,
       createdAt: wire.created_at,
       updatedAt: wire.updated_at,

package/src/partnership.ts

@@ -1,5 +1,7 @@
 import { z } from 'zod'
 
+import { convertedToWireSchema } from './conversion.ts'
+import type { ConvertedTo } from './conversion.ts'
 import { customFieldValuesBody, customFieldValuesSchema } from './customField.ts'
 import type { CustomFieldValue, CustomFieldValues } from './customField.ts'
 import { definedFields, idSchema, recordTimestamps } from './wire.ts'
@@ -23,6 +25,8 @@ export interface Partnership extends RecordTimestamps {
   readonly personIds: readonly string[]
   readonly summary: string
   readonly tags: readonly string[]
+  /** Non-null once this record has been converted to another pipeline type. */
+  readonly convertedTo: ConvertedTo | null
   /** Workspace-defined fields, keyed by definition key. Always present (default `{}`). */
   readonly customFields: CustomFieldValues
 }
@@ -41,6 +45,7 @@ export const partnershipSchema: z.ZodType<Partnership, unknown> = z
     person_ids: z.array(idSchema),
     summary: z.string(),
     tags: z.array(z.string()),
+    converted_to: convertedToWireSchema,
     custom_fields: customFieldValuesSchema,
     ...recordTimestamps,
   })
@@ -58,6 +63,10 @@ export const partnershipSchema: z.ZodType<Partnership, unknown> = z
       personIds: wire.person_ids,
       summary: wire.summary,
       tags: wire.tags,
+      convertedTo:
+        wire.converted_to === null
+          ? null
+          : { targetType: wire.converted_to.target_type, targetId: wire.converted_to.target_id },
       customFields: wire.custom_fields,
       createdAt: wire.created_at,
       updatedAt: wire.updated_at,

package/src/raise.ts

@@ -1,5 +1,7 @@
 import { z } from 'zod'
 
+import { convertedToWireSchema } from './conversion.ts'
+import type { ConvertedTo } from './conversion.ts'
 import { customFieldValuesBody, customFieldValuesSchema } from './customField.ts'
 import type { CustomFieldValue, CustomFieldValues } from './customField.ts'
 import { definedFields, idSchema, recordTimestamps } from './wire.ts'
@@ -24,6 +26,8 @@ export interface Raise extends RecordTimestamps {
   readonly personIds: readonly string[]
   readonly summary: string
   readonly tags: readonly string[]
+  /** Non-null once this record has been converted to another pipeline type. */
+  readonly convertedTo: ConvertedTo | null
   /** Workspace-defined fields, keyed by definition key. Always present (default `{}`). */
   readonly customFields: CustomFieldValues
 }
@@ -43,6 +47,7 @@ export const raiseSchema: z.ZodType<Raise, unknown> = z
     person_ids: z.array(idSchema),
     summary: z.string(),
     tags: z.array(z.string()),
+    converted_to: convertedToWireSchema,
     custom_fields: customFieldValuesSchema,
     ...recordTimestamps,
   })
@@ -61,6 +66,10 @@ export const raiseSchema: z.ZodType<Raise, unknown> = z
       personIds: wire.person_ids,
       summary: wire.summary,
       tags: wire.tags,
+      convertedTo:
+        wire.converted_to === null
+          ? null
+          : { targetType: wire.converted_to.target_type, targetId: wire.converted_to.target_id },
       customFields: wire.custom_fields,
       createdAt: wire.created_at,
       updatedAt: wire.updated_at,

package/src/session.ts

@@ -68,8 +68,6 @@ export interface Workspace {
   readonly name: string
   readonly slug: string
   readonly timezone: string
-  readonly tagline: string | null
-  readonly oneLiner: string | null
 }
 
 export const workspaceSchema: z.ZodType<Workspace, unknown> = z
@@ -78,8 +76,6 @@ export const workspaceSchema: z.ZodType<Workspace, unknown> = z
     name: z.string(),
     slug: z.string(),
     timezone: z.string(),
-    tagline: z.string().nullable(),
-    one_liner: z.string().nullable(),
   })
   .transform(
     (wire): Workspace => ({
@@ -87,8 +83,6 @@ export const workspaceSchema: z.ZodType<Workspace, unknown> = z
       name: wire.name,
       slug: wire.slug,
       timezone: wire.timezone,
-      tagline: wire.tagline,
-      oneLiner: wire.one_liner,
     }),
   )
 
@@ -102,19 +96,11 @@ export function createWorkspaceBody(input: CreateWorkspaceInput): Record<string,
   return { name: input.name, slug: input.slug, timezone: input.timezone }
 }
 
-/**
- * Settings a workspace admin can change.
- *
- * `tagline` and `oneLiner` are the two strings an agent reads to say who this
- * company is, so `null` clears them and `undefined` leaves them alone, per
- * `api.md`. `definedFields` is what keeps those two apart on the wire.
- */
+/** Settings a workspace admin can change. */
 export interface UpdateWorkspaceInput {
   readonly name?: string
   readonly slug?: string
   readonly timezone?: string
-  readonly tagline?: string | null
-  readonly oneLiner?: string | null
 }
 
 export function updateWorkspaceBody(input: UpdateWorkspaceInput): Record<string, unknown> {
@@ -122,8 +108,6 @@ export function updateWorkspaceBody(input: UpdateWorkspaceInput): Record<string,
     name: input.name,
     slug: input.slug,
     timezone: input.timezone,
-    tagline: input.tagline,
-    one_liner: input.oneLiner,
   })
 }
 

package/src/values.ts

@@ -356,6 +356,7 @@ export const FORM_FIELD_MAP_TARGETS = [
   'person.first_name',
   'person.last_name',
   'person.email',
+  'person.phones',
   'person.consent',
   'company.name',
   'company.domain',
@@ -367,13 +368,17 @@ export const FORM_FIELD_MAP_TARGETS = [
   'submission',
 ] as const
 
-export type FormFieldMapTarget = (typeof FORM_FIELD_MAP_TARGETS)[number]
+/** Any valid form map target string. See `formMapTargets.ts` for the full catalog. */
+export type FormFieldMapTarget = string
 
-export const FORM_FIELD_MAP_TARGET_LABELS: Readonly<Record<FormFieldMapTarget, string>> = {
+export const FORM_FIELD_MAP_TARGET_LABELS: Readonly<
+  Record<(typeof FORM_FIELD_MAP_TARGETS)[number], string>
+> = {
   'person.name': 'Person · name',
   'person.first_name': 'Person · first name',
   'person.last_name': 'Person · last name',
   'person.email': 'Person · email',
+  'person.phones': 'Person · phone',
   'person.consent': 'Person · consent',
   'company.name': 'Company · name',
   'company.domain': 'Company · domain',