@kelpie/schemas 0.7.0 → 0.9.0

package/src/company.ts

@@ -1,5 +1,7 @@
 import { z } from 'zod'
 
+import { customFieldValuesBody, customFieldValuesSchema } from './customField.ts'
+import type { CustomFieldValue, CustomFieldValues } from './customField.ts'
 import { ACCOUNT_TYPES, COMPANY_STAGES, ICP_FITS, SIZE_BANDS } from './values.ts'
 import type { AccountType, CompanyStage, IcpFit, SizeBand } from './values.ts'
 import { definedFields, idSchema, recordTimestamps } from './wire.ts'
@@ -22,6 +24,10 @@ export interface Company extends RecordTimestamps {
   readonly techStack: readonly string[]
   readonly summary: string
   readonly tags: readonly string[]
+  /** True when this Company represents the workspace itself ("us"). */
+  readonly isOwn: boolean
+  /** Workspace-defined fields, keyed by definition key. Always present (default `{}`). */
+  readonly customFields: CustomFieldValues
 }
 
 export const companySchema: z.ZodType<Company, unknown> = z
@@ -40,6 +46,8 @@ export const companySchema: z.ZodType<Company, unknown> = z
     tech_stack: z.array(z.string()),
     summary: z.string(),
     tags: z.array(z.string()),
+    is_own: z.boolean(),
+    custom_fields: customFieldValuesSchema,
     ...recordTimestamps,
   })
   .transform(
@@ -58,6 +66,8 @@ export const companySchema: z.ZodType<Company, unknown> = z
       techStack: wire.tech_stack,
       summary: wire.summary,
       tags: wire.tags,
+      isOwn: wire.is_own,
+      customFields: wire.custom_fields,
       createdAt: wire.created_at,
       updatedAt: wire.updated_at,
     }),
@@ -77,6 +87,12 @@ export interface CompanyInput {
   readonly techStack?: readonly string[]
   readonly summary?: string
   readonly tags?: readonly string[]
+  readonly isOwn?: boolean
+  /**
+   * Partial merge patch: sent keys change, `null` clears a key, absent keys are
+   * left alone. Unknown keys are rejected at `422`.
+   */
+  readonly customFields?: Readonly<Record<string, CustomFieldValue | null>>
 }
 
 export function companyBody(input: CompanyInput): Record<string, unknown> {
@@ -94,5 +110,8 @@ export function companyBody(input: CompanyInput): Record<string, unknown> {
     tech_stack: input.techStack,
     summary: input.summary,
     tags: input.tags,
+    is_own: input.isOwn,
+    custom_fields:
+      input.customFields === undefined ? undefined : customFieldValuesBody(input.customFields),
   })
 }

package/src/consentPurpose.ts

@@ -0,0 +1,95 @@
+import { z } from 'zod'
+
+import { CONSENT_PURPOSE_STATUSES } from './values.ts'
+import type { ConsentPurposeStatus } from './values.ts'
+import { definedFields, idSchema, recordTimestamps } from './wire.ts'
+import type { RecordTimestamps } from './wire.ts'
+
+/**
+ * Wire and write shapes for `/v1/consent_purposes`.
+ *
+ * A workspace defines its own purposes (`contact`, `marketing`, …). Every
+ * capture site — forms, lists, imports, the manual override on a Person —
+ * names one. Modelled on `custom_field_definitions`: `slug` is immutable and
+ * behaves as the key, `default_status` is the workspace default a person
+ * without an explicit `person_consents` row inherits, and `sort_order` runs
+ * 0..N-1 with the service renumbering on reorder and delete.
+ */
+
+/** A workspace's definition of one consent purpose. */
+export interface ConsentPurpose extends RecordTimestamps {
+  readonly id: string
+  /** Immutable after create. Lowercase snake_case, matches `/^[a-z][a-z0-9_]*$/`. */
+  readonly slug: string
+  readonly label: string
+  readonly description: string
+  /** The workspace default a person without an explicit row inherits. */
+  readonly defaultStatus: ConsentPurposeStatus
+  readonly sortOrder: number
+}
+
+export const consentPurposeSchema: z.ZodType<ConsentPurpose, unknown> = z
+  .object({
+    id: idSchema,
+    slug: z.string(),
+    label: z.string(),
+    description: z.string(),
+    default_status: z.enum(CONSENT_PURPOSE_STATUSES),
+    sort_order: z.number().int(),
+    ...recordTimestamps,
+  })
+  .transform(
+    (wire): ConsentPurpose => ({
+      id: wire.id,
+      slug: wire.slug,
+      label: wire.label,
+      description: wire.description,
+      defaultStatus: wire.default_status,
+      sortOrder: wire.sort_order,
+      createdAt: wire.created_at,
+      updatedAt: wire.updated_at,
+    }),
+  )
+
+/**
+ * The body a create takes. `slug` is only written here; a `PATCH` cannot
+ * change it — a rename would strand every stored `person_consents` row and
+ * every form/list/import that names the purpose.
+ */
+export interface CreateConsentPurposeInput {
+  readonly slug: string
+  readonly label: string
+  readonly description?: string
+  readonly defaultStatus?: ConsentPurposeStatus
+}
+
+export function createConsentPurposeBody(
+  input: CreateConsentPurposeInput,
+): Record<string, unknown> {
+  return definedFields({
+    slug: input.slug,
+    label: input.label,
+    description: input.description,
+    default_status: input.defaultStatus,
+  })
+}
+
+/**
+ * What a `PATCH` may change. `slug` is fixed for the purpose's lifetime and
+ * the strict body naturally makes it a `422`.
+ */
+export interface ConsentPurposeInput {
+  readonly label?: string
+  readonly description?: string
+  readonly defaultStatus?: ConsentPurposeStatus
+  readonly sortOrder?: number
+}
+
+export function consentPurposeBody(input: ConsentPurposeInput): Record<string, unknown> {
+  return definedFields({
+    label: input.label,
+    description: input.description,
+    default_status: input.defaultStatus,
+    sort_order: input.sortOrder,
+  })
+}

package/src/customField.ts

@@ -0,0 +1,211 @@
+import { z } from 'zod'
+
+import {
+  CUSTOM_FIELD_OBJECT_TYPES,
+  CUSTOM_FIELD_TYPES,
+} from './values.ts'
+import type { CustomFieldObjectType, CustomFieldType } from './values.ts'
+import { definedFields, idSchema, recordTimestamps } from './wire.ts'
+import type { RecordTimestamps } from './wire.ts'
+
+/**
+ * Wire and write shapes for `/v1/custom_fields`.
+ *
+ * The definition is workspace-scoped. Every record on the six object types
+ * carries a `custom_fields` object keyed by definition key; the values are the
+ * shape this file describes. The Zod layer here only checks structure — that a
+ * value looks like text / number / boolean / a string list / a money object —
+ * because the workspace's definitions are read from the database, not the
+ * request. Definition-aware checks (this key exists on this object type, this
+ * select value is one of the options) run in the service.
+ *
+ * Merge semantics on the record's `custom_fields` (documented in `api.md`): a
+ * `PATCH` sends the keys that change; `null` clears a key; an unknown key is
+ * `422` naming `custom_fields.<key>`.
+ */
+
+/**
+ * The value union a custom field can carry on the wire. Structural only — the
+ * validator in `@kelpie/server` reads the workspace's definitions and refuses a
+ * `number` written into a `text` field, an unknown `select` option, and so on.
+ *
+ * `text`, `long_text`, `url`, `date` and `select` all serialise as strings; a
+ * `multi_select` is a `string[]`; a `currency` is a small object; the rest are
+ * primitives. Nothing here reads a definition, so the caps below are the
+ * absolute ceilings meant to reject a runaway payload before it reaches the
+ * database, not the per-type limits (also enforced by the validator).
+ */
+export const customFieldWireValue = z.union([
+  z.string().max(65536),
+  z.number(),
+  z.boolean(),
+  z.array(z.string().min(1).max(120)).max(100),
+  z.strictObject({
+    amount_cents: z.number().int(),
+    currency: z.string().regex(/^[A-Z]{3}$/u),
+  }),
+])
+
+export type CustomFieldWireValue = z.infer<typeof customFieldWireValue>
+
+/** A value already parsed and rebuilt as the record the UI holds. */
+export type CustomFieldValue =
+  | string
+  | number
+  | boolean
+  | readonly string[]
+  | { readonly amountCents: number; readonly currency: string }
+
+/** The `custom_fields` object every record on the six object types carries. */
+export type CustomFieldValues = Readonly<Record<string, CustomFieldValue>>
+
+/**
+ * Parses the wire object into the record shape the UI works with. Currency is
+ * the one type that changes shape (`amount_cents` → `amountCents`); everything
+ * else is the same value.
+ */
+export const customFieldValuesSchema: z.ZodType<CustomFieldValues, unknown> = z
+  .record(z.string(), customFieldWireValue)
+  .transform((wire): CustomFieldValues => {
+    const out: Record<string, CustomFieldValue> = {}
+    for (const [key, value] of Object.entries(wire)) {
+      if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+        out[key] = { amountCents: value.amount_cents, currency: value.currency }
+      } else {
+        out[key] = value
+      }
+    }
+    return out
+  })
+
+/**
+ * The shape a record's `PATCH` accepts for `custom_fields`. A key's value is
+ * the wire value, or `null` to clear that key; unknown keys fail at the service
+ * layer with `422 custom_fields.<key>`.
+ */
+export const customFieldsPatchShape: z.ZodType<
+  Readonly<Record<string, CustomFieldWireValue | null>>,
+  unknown
+> = z
+  .record(z.string().min(1).max(64), customFieldWireValue.nullable())
+  .describe(
+    'Workspace-defined fields keyed by definition key. List the workspace\'s definitions with the custom_fields_list tool before writing. A key set to null clears the value; an unknown key is refused.',
+  )
+
+/**
+ * Turns the UI's record shape back into the wire object for a `PATCH` body.
+ * The inverse of `customFieldValuesSchema`.
+ */
+export function customFieldValuesBody(
+  values: Readonly<Record<string, CustomFieldValue | null>>,
+): Record<string, CustomFieldWireValue | null> {
+  const out: Record<string, CustomFieldWireValue | null> = {}
+  for (const [key, value] of Object.entries(values)) {
+    out[key] = wireCustomFieldValue(value)
+  }
+  return out
+}
+
+function wireCustomFieldValue(value: CustomFieldValue | null): CustomFieldWireValue | null {
+  if (value === null) return null
+  if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
+    return value
+  }
+  // Array.isArray does not narrow a `readonly` array literal, so branch on the
+  // currency object's shape and treat everything else as the string list.
+  if ('amountCents' in value && 'currency' in value) {
+    return { amount_cents: value.amountCents, currency: value.currency }
+  }
+  return [...value]
+}
+
+/** A workspace's definition of one custom field, for one object type. */
+export interface CustomFieldDefinition extends RecordTimestamps {
+  readonly id: string
+  readonly objectType: CustomFieldObjectType
+  /** Immutable after create. Lowercase snake_case, matches `/^[a-z][a-z0-9_]*$/`. */
+  readonly key: string
+  readonly label: string
+  /** Immutable after create. */
+  readonly type: CustomFieldType
+  /** Non-empty only for `select` and `multi_select`. */
+  readonly options: readonly string[]
+  readonly description: string
+  readonly sortOrder: number
+}
+
+export const customFieldDefinitionSchema: z.ZodType<CustomFieldDefinition, unknown> = z
+  .object({
+    id: idSchema,
+    object_type: z.enum(CUSTOM_FIELD_OBJECT_TYPES),
+    key: z.string(),
+    label: z.string(),
+    type: z.enum(CUSTOM_FIELD_TYPES),
+    options: z.array(z.string()),
+    description: z.string(),
+    sort_order: z.number().int(),
+    ...recordTimestamps,
+  })
+  .transform(
+    (wire): CustomFieldDefinition => ({
+      id: wire.id,
+      objectType: wire.object_type,
+      key: wire.key,
+      label: wire.label,
+      type: wire.type,
+      options: wire.options,
+      description: wire.description,
+      sortOrder: wire.sort_order,
+      createdAt: wire.created_at,
+      updatedAt: wire.updated_at,
+    }),
+  )
+
+/**
+ * The body a create takes. `object_type`, `key`, and `type` are only written
+ * here; a `PATCH` cannot change any of them (see `CustomFieldDefinitionInput`).
+ */
+export interface CreateCustomFieldDefinitionInput {
+  readonly objectType: CustomFieldObjectType
+  readonly key: string
+  readonly label: string
+  readonly type: CustomFieldType
+  readonly options?: readonly string[]
+  readonly description?: string
+}
+
+export function createCustomFieldDefinitionBody(
+  input: CreateCustomFieldDefinitionInput,
+): Record<string, unknown> {
+  return definedFields({
+    object_type: input.objectType,
+    key: input.key,
+    label: input.label,
+    type: input.type,
+    options: input.options,
+    description: input.description,
+  })
+}
+
+/**
+ * What a `PATCH` may change. `key` and `type` are fixed for the definition's
+ * lifetime — a change would strand records with the wrong value shape — and
+ * the strict body naturally makes either a `422`.
+ */
+export interface CustomFieldDefinitionInput {
+  readonly label?: string
+  readonly options?: readonly string[]
+  readonly description?: string
+  readonly sortOrder?: number
+}
+
+export function customFieldDefinitionBody(
+  input: CustomFieldDefinitionInput,
+): Record<string, unknown> {
+  return definedFields({
+    label: input.label,
+    options: input.options,
+    description: input.description,
+    sort_order: input.sortOrder,
+  })
+}

package/src/deal.ts

@@ -1,5 +1,7 @@
 import { z } from 'zod'
 
+import { customFieldValuesBody, customFieldValuesSchema } from './customField.ts'
+import type { CustomFieldValue, CustomFieldValues } from './customField.ts'
 import { definedFields, idSchema, recordTimestamps } from './wire.ts'
 import type { RecordTimestamps } from './wire.ts'
 
@@ -22,6 +24,8 @@ export interface Deal extends RecordTimestamps {
   readonly summary: string
   readonly tags: readonly string[]
   readonly externalId: string | null
+  /** Workspace-defined fields, keyed by definition key. Always present (default `{}`). */
+  readonly customFields: CustomFieldValues
 }
 
 export const dealSchema: z.ZodType<Deal, unknown> = z
@@ -41,6 +45,7 @@ export const dealSchema: z.ZodType<Deal, unknown> = z
     summary: z.string(),
     tags: z.array(z.string()),
     external_id: z.string().nullable(),
+    custom_fields: customFieldValuesSchema,
     ...recordTimestamps,
   })
   .transform(
@@ -60,6 +65,7 @@ export const dealSchema: z.ZodType<Deal, unknown> = z
       summary: wire.summary,
       tags: wire.tags,
       externalId: wire.external_id,
+      customFields: wire.custom_fields,
       createdAt: wire.created_at,
       updatedAt: wire.updated_at,
     }),
@@ -80,6 +86,11 @@ export interface DealInput {
   readonly summary?: string
   readonly tags?: readonly string[]
   readonly externalId?: string | null
+  /**
+   * Partial merge patch: sent keys change, `null` clears a key, absent keys are
+   * left alone. Unknown keys are rejected at `422`.
+   */
+  readonly customFields?: Readonly<Record<string, CustomFieldValue | null>>
 }
 
 export function dealBody(input: DealInput): Record<string, unknown> {
@@ -98,5 +109,7 @@ export function dealBody(input: DealInput): Record<string, unknown> {
     summary: input.summary,
     tags: input.tags,
     external_id: input.externalId,
+    custom_fields:
+      input.customFields === undefined ? undefined : customFieldValuesBody(input.customFields),
   })
 }

package/src/emailDomainLinker.ts

@@ -0,0 +1,28 @@
+import { z } from 'zod'
+
+/**
+ * Wire shape for `POST /v1/workspaces/:id/relink-email-domains`.
+ *
+ * The endpoint takes no body. The response counts what the sweep did: how
+ * many Companies were scanned and how many titleless Positions were newly
+ * created. A follow-up run on the same workspace returns the same count for
+ * `companies_scanned` and zero for `positions_created` — the sweep is
+ * idempotent (a person already linked to that company is skipped).
+ */
+
+export interface RelinkEmailDomainsCounts {
+  readonly companiesScanned: number
+  readonly positionsCreated: number
+}
+
+export const relinkEmailDomainsCountsSchema: z.ZodType<RelinkEmailDomainsCounts, unknown> = z
+  .object({
+    companies_scanned: z.number().int().nonnegative(),
+    positions_created: z.number().int().nonnegative(),
+  })
+  .transform(
+    (wire): RelinkEmailDomainsCounts => ({
+      companiesScanned: wire.companies_scanned,
+      positionsCreated: wire.positions_created,
+    }),
+  )

package/src/enquiry.ts

@@ -0,0 +1,94 @@
+import { z } from 'zod'
+
+import { customFieldValuesBody, customFieldValuesSchema } from './customField.ts'
+import type { CustomFieldValue, CustomFieldValues } from './customField.ts'
+import { definedFields, idSchema, recordTimestamps } from './wire.ts'
+import type { RecordTimestamps } from './wire.ts'
+
+/** Wire and write shapes for `/v1/enquiries`. */
+
+export interface Enquiry extends RecordTimestamps {
+  readonly id: string
+  readonly name: string
+  /** Free text ("Website", "Email", "Referral", …), like Opportunity's `kind`. */
+  readonly source: string
+  readonly stageId: string
+  /** Nullable: an early enquiry may arrive before a company is on file. */
+  readonly companyId: string | null
+  readonly ownerId: string | null
+  /** Non-null once the enquiry has been converted to a Deal; nulled if that deal is deleted. */
+  readonly convertedDealId: string | null
+  readonly personIds: readonly string[]
+  readonly summary: string
+  readonly tags: readonly string[]
+  /** Workspace-defined fields, keyed by definition key. Always present (default `{}`). */
+  readonly customFields: CustomFieldValues
+}
+
+export const enquirySchema: z.ZodType<Enquiry, unknown> = z
+  .object({
+    id: idSchema,
+    name: z.string(),
+    source: z.string(),
+    stage_id: idSchema,
+    company_id: idSchema.nullable(),
+    owner_id: idSchema.nullable(),
+    converted_deal_id: idSchema.nullable(),
+    person_ids: z.array(idSchema),
+    summary: z.string(),
+    tags: z.array(z.string()),
+    custom_fields: customFieldValuesSchema,
+    ...recordTimestamps,
+  })
+  .transform(
+    (wire): Enquiry => ({
+      id: wire.id,
+      name: wire.name,
+      source: wire.source,
+      stageId: wire.stage_id,
+      companyId: wire.company_id,
+      ownerId: wire.owner_id,
+      convertedDealId: wire.converted_deal_id,
+      personIds: wire.person_ids,
+      summary: wire.summary,
+      tags: wire.tags,
+      customFields: wire.custom_fields,
+      createdAt: wire.created_at,
+      updatedAt: wire.updated_at,
+    }),
+  )
+
+/**
+ * `convertedDealId` is deliberately absent from the input: it is set only by
+ * `POST /v1/enquiries/:id/convert`, and a `PATCH` that carried it is `422`.
+ */
+export interface EnquiryInput {
+  readonly name?: string
+  readonly source?: string
+  readonly stageId?: string
+  readonly companyId?: string | null
+  readonly ownerId?: string | null
+  readonly personIds?: readonly string[]
+  readonly summary?: string
+  readonly tags?: readonly string[]
+  /**
+   * Partial merge patch: sent keys change, `null` clears a key, absent keys are
+   * left alone. Unknown keys are rejected at `422`.
+   */
+  readonly customFields?: Readonly<Record<string, CustomFieldValue | null>>
+}
+
+export function enquiryBody(input: EnquiryInput): Record<string, unknown> {
+  return definedFields({
+    name: input.name,
+    source: input.source,
+    stage_id: input.stageId,
+    company_id: input.companyId,
+    owner_id: input.ownerId,
+    person_ids: input.personIds,
+    summary: input.summary,
+    tags: input.tags,
+    custom_fields:
+      input.customFields === undefined ? undefined : customFieldValuesBody(input.customFields),
+  })
+}